This document is intended to guide the systems administrator in setting up the Xkernel xterminal software. It covers installation, configuration options, and basic troubleshooting. There is also a quick overview of some related topics, like netbooting and the Sun OpenBoot PROM. While this document is mostly self-contained, it is assumed that the reader is familiar with basic UNIX commands and procedures. Introduction ============ The Xkernel software provides a kit for turning older Sun workstations into xterminals. This can extend the useful life of older hardware because the same machine is usually faster as an xterminal than as a workstation. The difference is simply that most of the services available on a workstation are removed from the xterminal. Typical xterminal setups are described in this document. Appendix C contains a few hints on unusual setups that may be desirable in particular situations. Hardware support ================ If the reader is sufficiently industrious, anything can be made to work. This section describes the hardware that is supported by default, without any extraordinary effort on the part of the systems administrator. Xkernel supports the following kinds of machines: sun3 3/50, 3/60, 3/150, 3/180, 3/280 sun3x 3/80, 3/480 sun4c SPARCstation 1, 1+, 2, "2+", IPC, IPX, SLC, ELC sun1, sun2, sun4m (SS10 & 20), sun4d (SS1000 & 2000), and sun4u (UltraSPARCs) are not supported. sun3 systems are supported with or without an FP coprocessor (68881). Xkernel supports the following kinds of framebuffers: VME: bwtwo, cgtwo, cgthree P4: cgfour SBus: bwtwo, cgthree, cgsix Other framebuffers are not necessarily supported, but some may work. The author has only the above framebuffers available to test. Xkernel supports Lance (le*) and Intel (ie*) ethernets. Other network interfaces are not supported. Xkernel supports all normal Sun mice, keyboards, and monitors. Setting it up ============= The following objectives comprise the setup: - assemble the hardware for the xterminal(s) - install the Xkernel software and NFS export it to the xterminal(s) - collect the IP and ethernet address(es) of the xterminal(s) - edit the ethers and bootparams files and/or NIS maps - edit the Xkernel hosts, defaultrouter, fstab, and Xkernel.conf files - install the appropriate tftp boot image(s) - enable RARP and TFTP on each relevant network or subnet - set up XDM - boot the xterminal(s) Each of these steps is explained in this section. After following these steps, the xterminal should boot and be useable. If problems arise, refer to the troubleshooting section. Assembling xterminal hardware ----------------------------- A Sun xterminal is set up like any other Sun, but it requires no disk, and possibly somewhat less memory. Assemble a chassis with memory, framebuffer, keyboard, mouse, and monitor in some supported configuration (see above). Install as much memory as you have, since memory for these systems is less than useful today. The minimum is about 4Mb per b&w head, and 8Mb per color head. For example, a dual- headed 3/150 xterminal with a bwtwo and cgthree would need at least 12Mb of RAM. It's ill-advised to put disks in xterminals. It's possible to do so, but the default configuration does not take that possibility into account. The idea of adding swap to an xterminal instead of providing the minimum amount of RAM is a particularly bad one. Installing the Xkernel software ------------------------------- Booting xterminals through a router is not an option. There must be a RARP/TFTP server on the same subnet as the xterminal, and it is extremely desirable for the server of the xterminal's root partition be one the same subnet as the xterminal. The recommended, and simplest, configuration is to have RARP, TFTP, and NFS exports on the same server. A single server can either have interfaces on all networks containing xterminals, or multiple servers can be used. Using multiple RARP and/or TFTP servers on a single subnet tends to cause problems and should be avoided. Multiple NFS servers on a single subnet is ok. Parts of the Xkernel software are platform independent. Other parts depend on the kernel architecture of the xterminal in question, and/or on whether or not it has an FP coprocessor. In particular: The kernel, vmunix, is sensitive to the kernel architecture. The X server, Xsun*, is sensitive to the architecture, and the presence of an FP coprocessor. Because of the way the software is arranged, xterminals differing in the above listed particulars cannot share an NFS root area. A separate area must be established for each class of xterms. A typical installation looks like this: /export/root/Xkernel/Xkernel.sun3/ /export/root/Xkernel/Xkernel.sun3-nofp/ /export/root/Xkernel/Xkernel.sun3x/ /export/root/Xkernel/Xkernel.sun4c/ These partitions should be NFS exported from the server to all of the appropriate xterminals in /etc/exports (/etc/dfs/dfstab under Solaris). A typical installation uses netgroups, for example: --- /etc/netgroup --- sun3_xterminals \ (yamato.rutgers.edu,-,-) \ (madeira.rutgers.edu,-,-) sun4c_xterminals \ (cat-in-the-hat.rutgers.edu,-,-) \ (tehran.rutgers.edu,-,-) \ (javapot.rutgers.edu,-,-) sun_xterminals \ sun3_xterminals \ sun4c_xterminals --- end /etc/netgroup excerpt --- --- /etc/dfs/dfstab --- /usr/sbin/share -F nfs -o anon=0,ro=sun_xterminals /export/root/Xkernel --- end /etc/dfs/dfstab excerpt --- There are a couple of kernels in the Xkernel root area. Depending on which flavor of the Xkernel package is installed, it may be necessary to adjust the XKERNELROOT/vmunix symlink. vmunix should either be the correct kernel, or a symlink to it. This is primarily of interest to those using the sun3 Xkernel and making separate areas for machines with and without FP coprocessors. The other symlink(s) that may need to be adjusted related to fonts. These are described in Appendix B, Fonts. Configuration of the Xkernel software for individual xterminals is addressed below. Collecting xterminal-specific data ---------------------------------- From the "ok" prompt (OBPv2) on the xterminal, the "banner" command will display, among other things, the ethernet address for the xterminal. For machines with a ">" prompt (OBPv0), the banner is displayed on power-on. Contact the local hostmaster to acquire IP addresses for the xterminals. Each xterminal needs its own hostname and IP address. If DNS is not being used, simply add the xterminal names and IP addresses to the server's /etc/hosts. Edit /etc/ethers and /etc/bootparams ------------------------------------ /etc/ethers should be filled with lines like this: --- /etc/ethers --- 8:0:20:d:f3:a7 truffula-tree.rutgers.edu --- end /etc/ethers excerpt --- There must be an entry for each xterminal, and there should not be duplicate entries. /etc/bootparams should be filled with lines like this: --- /etc/bootparams --- heathen.rutgers.edu root=farside:/export/root/Xkernel/Xkernel.sun4c --- end /etc/bootparams excerpt --- There must be an entry for each xterminal. There should not be duplicate entries. If NIS is being used, once these files have been edited the maps must be remade. Normally, in.rarpd and rpc.bootparamd do not need to be restarted. Be particularly careful that there is either only one server on any given subnet, or that all servers on each subnet have the same data. Servers with conflicting data will cause problems. Edit the Xkernel configuration files ------------------------------------ In the Xkernel root area, there are two files that normally need to be edited to add an xterminal to an existing installation, and an additional two files that need to be edited when setting up a new installation. For new installation, the defaultrouter and fstab files must be set up appropriately. To use proxy ARP (a suggested configuration), simply skip the installation of a defaultrouter file. The Xkernel software will do the right thing if XKERNELROOT/etc/defaultrouter is not found, as long as each xterminal's address is in XKERNELROOT/etc/hosts. If installed, XKERNELROOT/etc/defaultrouter should look like this: --- defaultrouter --- 128.6.5.15 --- end defaultrouter --- Where the example IP address is replaced by the IP address of the router on that subnet. fstab should be edited to reflect any additional mounts that are required. This is usually only NFS font service. For example: --- fstab --- paul:/grad/s4/Xkernel/usr /usr nfs ro 0 0 lcsrfonts:/rutgers/fonts/sun/X11 /nfs/X11 nfs ro,bg 0 0 --- end fstab --- The above example has some fonts mounted from the Xkernel NFS server, and others mounted from some other machine, lcsrfonts. To add an individual xterminal, the Xkernel hosts and Xkernel.conf files must be edited. The Xkernel hosts file, XKERNELROOT/etc/hosts, must contain entries for each xterminal sharing this root area, and also for the Xkernel root NFS server, any XDM servers, and any other servers used by the xterminal, e.g. NFS font servers. For example: --- hosts --- # 127.0.0.1 localhost # 128.6.13.2 romulus.rutgers.edu romulus 128.6.13.3 remus.rutgers.edu remus 128.6.13.26 igor.rutgers.edu igor lcsrfonts.rutgers.edu lcsrfonts # # XDM hosts # # They're all servers anyway. # # Xterminals addresses ... needed for default route # 128.6.13.7 berry.rutgers.edu berry 128.6.13.20 parsons.rutgers.edu parsons --- end hosts --- The Xkernel.conf file controls the behaviour of individual xterminals sharing the root area. It's in the form of a Bourne shell script, so potentially any shell hackery can be committed there. Its normal form is something like this: --- Xkernel.conf --- # # Xkernel.conf ############################ # First, set or unset and site settings # unset FONTSERVER # assume XDMHOST will provide fonts XDMHOST=george.rutgers.edu XDMMODE=query SYSLOGDEVICE=/dev/null ############################ # Second, host specific settings # case "$hostname" in blue-cheer.rutgers.edu) # sun3x XDMHOST=george.rutgers.edu XSERVER=/Xsun ;; clash.rutgers.edu) XDMHOST=george.rutgers.edu XSERVER=/XsunMono ;; silver-beetles.rutgers.edu) # sun3x # Sun 3/80 with a cgfour ARGS="-dev /dev/cgfour0 -zaphod" XDMHOST=paul.rutgers.edu XSERVER=/Xsun ;; yamato.rutgers.edu) ARGS="-dev /dev/cgtwo0 -zaphod" XDMHOST=caip.rutgers.edu XSERVER=/Xsun ;; esac --- end Xkernel.conf --- In the example above, all machines use NFS fonts, not an X fontserver. The default XDM host is george.rutgers.edu, and syslogging is disabled. blue-cheer is a Sun 3/80 with a color framebuffer of some kind, so it runs Xsun, the full X server. clash is a 3/50 with a b&w monitor. It can economize on memory by running the monochrome-only X server, XsunMono. silver-beetles has a cgfour. The ARGS variable is passed to the X server, in this case using the cgfour, but disabling hardware framebuffer switching. yamato has more than one framebuffer installed, but only the cgtwo should be used. Installing the TFTP boot image ------------------------------ The TFTP boot images are very specific to the machines they're for. They cannot be interchanged. The following images are available: boot.sun3 For any sun3 boot.sun3x For any sun3x boot.sun4c For any sun4c except SPARCstation 2 (Sun 4/75) boot.sun4c.ss2 For SPARCstation 2 (Sun 4/75) These images should be world readable, and installed in the /tftpboot directory of the chosen server. Normally, this is the same as the RARP and bootparams server. A symlink is required for each xterminal. It should point to the appropriate TFTP boot image for that xterminal. The form of the symlink depends on the architecture of the xterminal: sun3 80061A23 sun3x 80061A23.SUN3X sun4c 80061A23.SUN4C The secret numbers are the IP address (here 128.6.26.35) of the xterminal in hexadecimal. The extensions are required for the sun3x and sun4c. For the hexadecimally challenged, adb (among other tools) can be used to convert numbers: echo "0t26=X" | adb # decimal to hexadecimal echo "1a=D" | adb # hexadecimal to decimal Be sure to include leading zeros as appropriate. The symlink name must have exactly eight characters worth of hexadecimal IP address. Enabling RARP and TFTP ---------------------- Suns normally start in.rarpd and bootparamd if /tftpboot exists at boot time. If those daemons are already running, nothing should need to be changed. If not, either reboot the server or start the daemons by hand with the commands found in the rc scripts, e.g.: /usr/sbin/in.rarpd -a /usr/sbin/rpc.bootparamd TFTP must be enabled in /etc/inetd.conf. Here's the relevant line for Solaris: --- from /etc/inetd.conf --- # Tftp service is provided primarily for booting. Most sites run this tftp dgram udp wait root /usr/sbin/in.tftpd in.tftpd -s -d /tftpboot --- end /etc/inetd.conf excerpt --- Send inetd a SIGHUP to get it to reread its configuration file, except under IRIX, where it must be restarted because the IRIX inetd is borken. Setting up XDM -------------- The details of setting up XDM are beyond the scope of this document. On a modern Solaris system, dtlogin speaks XDMCP and can serve as an XDM agent. If actual XDM is being used, its configuration files live in XROOT/lib/X11/xdm/, for example /usr/local/X11/lib/X11/xdm/. Usually Xaccess, Xservers, Xsession, and Xstartup need to be edited. Then xdm needs to be started from the rc scripts. Booting the xterminal --------------------- Before booting the xterminal, it should be set to boot from the net by default. See Appendix A for details on how to accomplish this. After the above steps are completed, either powercycle the xterminal or give it the appropriate boot sequence (see Appendix A) to get it to boot. Then refer to the Troubleshooting section to find out what went wrong. Troubleshooting =============== During the boot: Error Diagnosis ------------------------ ----------------------------------------------------- The export didn't work NFS server not running; reboot or start manually client got error 0xd: need to export root area rw client got whoami: ... wrong tftp boot image for that machine client got RARP: ... rarpd not running client got RARP: ... ethers botched; fix & make NIS client got RARP: ... net not connected client got XUnable to dfstab botched client got XUnable to NFS exports botched client got X Error 1 fonts hosed; check font server & Xkernel fstab bad rarp/bootparams data multiple servers on this net? no rarp/bootparams ethers/bootparams/tftpboot dir botched no rarp/bootparams There's an SGI, or some other fast system on this net that doesn't have the appropriate rarp/bootparams data, and it's confusing the client. Either install the proper data or don't have multiple servers. xterm boots from disk PROM set incorrectly; see Appendix A xterm boots from disk Diag switch on back set to Diag, not Norm ... Looping XDM not running on server After the boot: Error Diagnosis ------------------------ ----------------------------------------------------- panic: init died Xkernel root server crashed or unexported root Watchdog Reset bad hardware Memory fault bad hardware Problems to note ---------------- Using the setup from LCSR-CF, dtlogin does not get the proper fonts. It works, but it's slow, and the fonts for the login screen are really small. If defaultrouter is used, root areas are network-specific. Sun 3s with PROMs below 1.6 work, but they can be painfully slow to boot, especially on crowded networks. Appendix A: Sun OpenBoot PROM ============================== This is a *very* short course in settings for the Sun OpenBoot PROM. For a more detailed overview, consult Sun's OBP documentation, the Sun FE manual, or the author's document on OBP and kadb. There are two kinds of PROM prompts from an xterminal, ">" (OBPv0) and "ok " (OBPv2). The transition PROM, that prompts the user to type "b" or "c", or "n" for new command mode, should be treated as OBPv2 after typing "n". OBPv0 commands other than b and c will not work. OBPv0 ----- See the PROM documentation for more details. To set a system with OBPv0 to boot from the net, type the following magical incantation: q 18 12 6c 65 . This will set the xterminal to boot from the NVRAM programmed device (the 12), and set that device to be the net (the 6c and 65). To check this information without changing anything, do the following: q 18 RET RET RET . This will print the contents of those addresses, but nothing will be changed if you type return instead of a new number to insert. The values displayed should be 12, 6c, and 65. If there is a Diag(nostic) switch on the back of the xterminal, make sure it is set to Norm(al), not Diag(nostic). OBPv2 ----- "printenv" will list the current settings. The ones that are relevant to xterminalization are input-device, output-device and boot-device. They should be set as follows: setenv input-device keyboard setenv output-device screen setenv boot-device net The "reset" command should be used after making changes. Note that if diag-switch? is set to true, diag-device will be used instead of boot-device as the device to boot from. It may also be desirable to skip the memory selftest. This can be effected with setenv selftest-#megs 0 Appendix B: Fonts ================= Fonts must be available to the X server in order for many normal X functions to work. These fonts can be provided through the two mechanisms X provides -- the X fontserver and the filesystem. The author has not had particularly good experiences with the X fontserver, and it is not documented here. NFS-mounted fonts can come from a central font server, from the Xkernel root NFS server, or both. It suffices to simply mount the font area from a central font server, but the author has found that it is sometimes desirable to have a local font cache on the Xkernel root NFS server. Mounting NFS fonts ------------------ fstab on in the Xkernel root area must be modified to mount NFS fonts from a server. A line will likely look like this: --- from fstab --- lcsrfonts:/rutgers/fonts/sun/X11 /nfs/X11 nfs ro,bg 0 0 --- end fstab excerpt --- Handling font paths ------------------- The X server must be able to find fonts to use. This is done through the X font path. The X font path may be set in a number of places. The most common are in the XDM startup scripts and in the user's personal startup script, .xsession. The directories in the X font path are resolved by the X server where it runs, i.e. on the xterminal. This means that those directories need to be available on the xterminal. It also means that fonts in odd places, for example in user home directories, won't work on an xterminal, since those directories are not normally available there. The X font path usually consists of a fairly small set of path components: --- example font paths --- /usr/local/X11/lib/fonts/75dpi/ /usr/local/X11R5//lib/fonts/75dpi/ /usr/X11/lib/fonts/75dpi/ /usr/local/fonts/75dpi/ --- end example font paths --- It's possible to simplify administration of the Xkernel area by making /usr on the xterminal be a nest of symlinks pointing to `.'. For example: root@remus: /ug/s0/Xkernel/usr 2# ls -l total 86 drwxr-sr-x 2 root root 5120 Oct 19 1993 100dpi/ drwxr-sr-x 2 root root 5120 Oct 19 1993 75dpi/ drwxr-sr-x 2 root root 512 Oct 19 1993 PEX/ drwxr-sr-x 2 root root 512 Oct 19 1993 Speedo/ drwxr-sr-x 2 root root 512 Oct 19 1993 Type1/ lrwxrwxrwx 1 root root 1 Jun 26 19:39 X11 -> ./ lrwxrwxrwx 1 root root 1 Jun 26 19:39 X11R4 -> ./ lrwxrwxrwx 1 root root 1 Jun 26 19:39 X11R5 -> ./ drwxr-xr-x 2 root root 2560 Aug 26 1994 andrew/ lrwxrwxrwx 1 root root 1 Jun 26 19:39 fonts -> ./ lrwxrwxrwx 1 root root 1 Jun 26 19:39 lib -> ./ lrwxrwxrwx 1 root root 1 Jun 26 19:39 local -> ./ drwxr-sr-x 2 root root 3584 Oct 20 1993 misc/ drwxr-sr-x 2 root root 8192 Oct 19 1993 openlook/ -rw-r--r-- 1 root root 4096 Aug 29 1992 rgb.dir -rw-r--r-- 1 root root 29696 Aug 29 1992 rgb.pag -rw-r--r-- 1 root root 16992 Aug 29 1992 rgb.txt lrwxrwxrwx 1 root root 1 Jun 26 19:39 sun -> ./ lrwxrwxrwx 1 root root 13 Jun 26 19:39 xtex -> /nfs/X11/xtex root@remus: /ug/s0/Xkernel/usr 2# In this example, there is an Xkernel /usr directory (set in the Xkernel fstab to mount as /usr on each xterminal) that contains almost all of the fonts needed for the X server. xtex fonts are mouned from some other font server (actually lcsrfonts from the fstab example above, mounted on /nfs/X11). Local font caching ------------------ The decision on whether or not to have a local font cache is up to the systems administrator. The decision is primarily an estimation of the stability of a central NFS font server. xterminals are quite sensitive to the availability of fonts. If the central NFS font server or the network from the xterminal to that server are flaky, the xterminal's performance will suffer. In that situation, a font cache would be useful. A font cache is nothing more than a duplication of some (or all) of the fonts from the central NFS font server on the machine that houses the Xkernel root area. The idea is that if the Xkernel root NFS server crashes, the xterminal would crash anyway, so the loss of fonts is immaterial. Maintaining a local font cache has the drawback that updates to the central NFS font server must be monitored and duplicated in the cache, or version slip will occur. An example ---------- As complete example of X font service, at LCSR-CF, the following configuration is used: Xkernel root is served by a different server on each subnet. Each Xkernel root server also has a local font cache. This cache is called "usr", and is mounted on each xterminal as /usr. This cache contains all of the normally used fonts at LCSR-CF except xtex. The ls output in the above example shows its contents. xtex fonts are mounted from LCSR-CF's central font server, lcsrfonts. They are mounted under /nfs/X11, and /usr/xtex is a symlink into there. All mounts are controlled by the Xkernel fstab. Here is the typical one used in LCSR-CF: --- Xkernel fstab --- paul:/grad/s4/Xkernel/usr /usr nfs ro 0 0 lcsrfonts:/rutgers/fonts/sun/X11 /nfs/X11 nfs ro,bg 0 0 --- end Xkernel fstab --- This mounts the local font cache (from Paul), and the central font server's area, for xtex (from lcsrfonts). Appendix C: Advanced configurations =================================== This section is pretty thin except for the following observation on the extensibility of Xkernel. The assumption is that if a systems administrator wants to do strange things with Xkernel but doesn't understand how it works, maybe the strange things should be rethought. Since the Xkernel software is really just a stripped down SunOS, it's possible to do anything with an xterminal that could be done with an equivalent workstation. Of course, the systems administrator will need to understand exactly what system services are needed for that particular function and install them into Xkernel, as almost everything in SunOS (except the X server) has been removed. It's also possible to turn another operating system, e.g. Linux, into an Xkernel-like package. A quick poke through sbin/init (a shell script in Xkernel) will give a good idea how it's done. Credits ======= Thanks to the Laboratory for Computer Science Research Computing Facility (LCSR-CF) and the Center for Computer Aids for Industrial Productivity (CAIP Center), both at Rutgers University, for providing me with access to all kinds of ancient and decrepit hardware on which to test my ideas. Thanks also go to the following individuals: Robert G. Mende, Jr. My boss at the CAIP Center Seth Robertson Creater of the Xkernel package David D. Rukshin My coworker at the CAIP Center