
Hi.


WHAT THIS IS

These are installation instructions for Linux Xkernel.  Linux Xkernel
is a package that allows you to boot your color or monochrome Sun3 or
Sun4c over an ethernet cable connected to your Linux machine.  When it
is all properly installed, the Sun will come up with a login screen
to log in to Linux.  However, it may take some work to get it to that
point.

For those with the necessary prowess, this package does offer some
rewards.  I can tell you from experience that it is *much* easier on
the eyes to program on a 19" monochrome Sun3 monitor than it is to
program on 13", 14", or 15" PC monitors.  Sun3's are also cheaper than
buying a big monitor for your PC.

This package is based on Seth Robertson's Xkernel-2.0 distribution
found on sol.ctr.columbia.edu, which is also the main distribution
point for Linux Xkernel.  The Sun3 kernel included here has a patch
for 1k NFS, but this should no longer be needed for any Linux system.
Hence, if the kernel or Xsun included with this package is not exactly
right for your system, you should be able to get another from
sol.ctr.columbia.edu that is more appropriate.

WHAT YOU NEED

In addition to this package, you will need to recompile your kernel to
include RARP support, you will need to have a reasonably complete X11
distribution, including fs and an xdm that supports XDMCP and your
password scheme (i.e. you need a different xdm if you use shadow
passwords than if not.).  You will also need to have networking set up
properly with your ethernet card (read the FAQ's and HOWTO's).

Before you even think about installing Xkernel, it is essential that
you get the appropriate kernel with RARP support and the appropriate
networking code installed and configured.  Without this, Xkernel
simply will not work.  If you don't _know_ your networking code is
working, you can safely assume that it is the problem if Xkernel
fails.


EXTRACTING

The Linux Xkernel package is meant to be extracted into /usr.
i.e. assuming the package is named "linux-xkernel.tar.gz", run (as
root)

zcat linux-xkernel.tar.gz | (cd /usr ; tar -xf -)

This will create the directory /usr/export and extract the package
into this directory.  The package takes approximately 3 megs of disk
space for a Sun3, and approximately 4 megs for a Sun4c, and about 7
megs if you want both.  If you prefer, you can extract it elsewhere
and make a symbolic link from /usr/export to wherever you extracted
it.  By default, the package includes everything for a Sun3 and for a
Sun4c, so you can save yourself some disk space by removing the
unnecessary directory in /usr/export/root/.


INSTALLATION

After the new kernel has been installed, the networking code has been
properly set up, and the Xkernel package is properly extracted,
perform the following steps to configure Xkernel.  Before performing
any step, read the entire instructions for that step. (just to be
safe...)

0) Recompile your kernel, set up networking, etc.

The Xkernel package assumes your machine is set up properly for
networking over an ethernet card.  If your machine is not set up for
this, set it up now.  The Xkernel package also requires a kernel with
RARP support.  You must reconfigure your kernel to add this support,
and then recompile and reinstall your kernel.  Note: your kernel has
RARP support if the file /proc/net/rarp exists.


1) Setting up hosts files.

Since you have set up the networking code, you should already have an
internet address (IP number) for your PC.  For Xkernel, you also need
an internet number for your Sun3.  If you network with other people,
you need to coordinate your choice with them.  (This is especially
true if you are on the internet!)  If you are setting this up on your
own private ethernet, you can choose anything you like, within the
constraints of your netmask.  For those unfamiliar with netmasks
(hopefully no one), you are generally OK so long as the first three
numbers of the PC's address match the first three numbers of the
Sun3's address.

I will now assume that you have an IP number.  I am currently using
1.2.3.4 for my Linux PC, 1.2.3.5 for my Sun3, and 1.2.3.7 for my Sun4c,
so you will see these numbers as examples below.  Now that you have an
IP number for your Sun, add it to /etc/hosts with a line as follows:

	1.2.3.5 xhost
	1.2.3.7 xhost-sparc

Call the Sun xhost if it is a Sun3, or xhost-sparc if it is a Sun4c.

Also in /etc/hosts, add the name "server" to the end of the list of
names for your Linux machine.  Don't add it to the beginning of the
list, because the beginning of the list is the machine's name.  Names
after the first one are aliases for the machine, and that's what you
want -- for server to be an alias for your NFS server.  This specifies
which machine will be the NFS server for the Sun3.

In addition, change the addresses in the files

	/usr/export/root/Xkernel.sun3/etc/hosts
and/or
	/usr/export/root/Xkernel.sun4c/etc/hosts 

to match those of your Sun3 (xhost), Sun4c (xhost-sparc) and your linux
machine (server).  Don't change anything else besides the IP
addresses.


2) Setting up rarp.

Next, the rarp command should be installed as /sbin/rarp.  Check this.
If it is not installed, install it.

Next determine the ethernet number of your Sun3/Sun4c.  It prints this when
it tries to boot.  Suppose it is 08:00:20:00:c6:00.  Then add a line
at the end of rc.local (in slackware /etc/rc.d/rc.local) like this:

	/sbin/rarp -s xhost 08:00:20:00:c6:00

This will add the Sun3 to your Linux rarp cache on every boot.  If you have
a Sun4c, that's not enough.  You also need to add Sun4c's to the ARP cache.
To do this, add not one but two lines to rc.local like this:

	/sbin/rarp -s xhost-sparc 08:00:20:03:06:d0
	/sbin/arp  -s xhost-sparc 08:00:20:03:06:d0

While you're editing rc.local, you might want to add two more things that
will be discussed later.  Add these two lines as well:

	/usr/bin/X11/xfs -config /usr/export/fsconfig &
	/usr/export/src/bootparamd/rpc.bootparamd

This will save you time in some of the later steps.


3) Setting up tftpd.

This package includes a tftpd server, specially modified for this
package.  It enhances security by adding the path
"/usr/export/tftpboot/" to the beginning of all requested files.  In
addition, it removes a bug found in some Linux tftpd's that causes
them to refuse requests for files without complete paths.  

One more enhancement is some additional logging through syslog.  If
you are having trouble getting Xkernel working and you suspect it is
tftp, try adding a line like this to /etc/syslog.conf:

	*.*	/dev/console

And then type (as root)

	killall -HUP syslogd

You will then see all syslog messages on your console, and so you
can easily debug tftp by the error messages it prints.

Compile tftpd from the source in /usr/export/src/tftpd, by going to
that directory and typing "make".  tftpd is started by inetd when
there is a tftp request.  To make sure this happens, check
/etc/inetd.conf for a line something like the line below:

	# tftp dgram udp wait nobody /usr/sbin/tcpd in.tftpd

Change it to be like this:

	tftp dgram udp wait nobody /usr/sbin/tcpd /usr/export/src/tftpd/tftpd

Next, change the internet address of the Sun3 to hexadecimal.  For
example, for my Sun3 which I have set up with IP number 1.2.3.5,
I convert to hex as follws: 1 is $01 in hex, 2 is $02, 3 is $03,
and 5 is $05.  So altogether, the internet address in hex is
01020305. Then do (replacing the number with yours)
   
	cd /usr/export/tftpboot ; ln -s boot.sun3.sunos.4.1.1 01020305

For a Sun4c, do the same thing, but add ".SUN4C" to the
end and link with the sun4c booter, like so:

	cd /usr/export/tftpboot ; ln -s boot.sun4c.sunos.4.1.3 01020307.SUN4C


4) Setting up bootparamd.

Compile bootparamd from the source in /usr/export/src/bootparamd.  You
should just need to type "make".

This bootparamd has been modified to use the file /usr/export/bootparams 
instead of the more common /etc/bootparams, so you only need to add
the following line to your rc.local file to start it up:  (You probably
did this in Step 2.)

	/usr/export/src/bootparamd/rpc.bootparamd

Finally, check your startup scripts to make sure that rpc.portmap is
run at startup.  Because rpc.bootparamd is run from rc.local, it will
be run after rpc.portmap.  (Order IS important.  If you need to make
changes, be sure rpc.portmap is run FIRST.  rpc.portmap must also be
run before the NFS daemon on startup!)

If portmap is not running, you can enable portmap by looking in
/etc/rc.d/rc.inet2, finding these lines (commented out), and putting
the lines in uncommented.

	# Start the SUN RPC Portmapper.
	if [ -f ${NET}/rpc.portmap ]
	then
	  echo -n " portmap"
	  ${NET}/rpc.portmap
	fi


5) Setting up nfsd.

You need an NFS daemon, rpc.nfsd, and a mount daemon, rpc.mountd.
These should already be in your /usr/sbin directory, along with
rpc.portmap, so you won't need to compile them.

WARNING: The latest nfsd (or the one included with your distribution)
may not be the best.  Some nfsd's have bugs.  If you get funny
messages (Especially "Init Died" messages) after the Sun's kernel has
loaded, suspect nfsd and try it again with the version of rpc.nfsd and
rpc.mountd that are included with the package.

MORE INFO: Some of these problems seem to be related to bugs that
don't allow opening for writing of files on NFS mounted read-only file
systems.  This is important, because the /devs directory is mounted
read-only (for security).  You can write to these devices, even though
they are on a read-only partition, because of their special nature.
Hence, it is important that the NFS server allow opening them for
writing, if they are devices, even when they are mounted read-only.

To compile and install the nfs server included with the package, do
this:

	cd /usr/export/src/nfs-server
	./configure
	make
	mv rpc.nfsd /usr/sbin/
	mv rpc.mountd /usr/sbin/

Now that nfsd is installed, add the contents of the file
/usr/export/exports to the file /etc/exports.

Check that rpc.nfsd and rpc.mountd are run from your startup scripts
(probably in /etc/rc.d/rc.inet2).  They should be run after
rpc.portmap.  If rpc.portmap was commented out, they will probably be
somewhere there but commented out too.

6) Setting up xdm.

You need a version of xdm that supports XDMCP terminals.  The versions
included with XFree86 2.0 or later should support XDMCP.  If you use
shadow passwords, you may need a special xdm.  Think of getting a
special xdm if you find that xdm won't accept your password and so you
can't log on.

By default, xdm will probably (depending on your configuration) start
X on your linux box when it is run.  If you don't want xdm to do this,
you will need to comment out the ":0 local" line in
/usr/lib/X11/xdm/Xservers.  For xdm to manage your Sun3, you may need
to add to the top of /usr/lib/X11/xdm/Xaccess the line

	xhost
and/or
	xhost-sparc

This tells xdm that the host "xhost" is allowed to connect to your
Linux machine.  Add this now.  If you are security conscious, you may
also want to add a line like this after the lines above:

	!*

This line tells xdm to not accept connections from any other hosts.

You will need to run xdm every time your system is booted, in order to
serve the Sun3/Sun4c X terminal.  

One way to do this is to add at the end of rc.local the command
"/usr/bin/X11/xdm", or whatever runs xdm on your system.  Note that I
have included the full path.  The reason for this is to make the
command line longer.  This is useful when running xdm, since xdm tries
to report a little of what it is doing by changing its command line as
seen by the "ps" command.  It is limited to the original command line
length, however, so it is nice to make it reasonably long.

Another way to start xdm is through init.  On slackware systems, you
can get an xdm system by changing the default run level from 3 to 4.
Note: only do this if you are using xdm as the primary way to log in
to your machine, in addition to using it for X terminals.

7) Fonts -- NFS Fonts vs. the fs Font Server

With fonts you have a choice of how you want to set things up.  The
font server is the default, since it works with compressed fonts.
However, if you have lots of disk space but are low on memory, you may
want to switch to nfs fonts.  

NOTE: In recent memory, I have only used xfs.  The material here about
using nfs fonts is old.  It may or may not still be reliable.  I
recommend you do Step 8, and not Step 9.

Compressed fonts cannot be used with the Sun3 Xsun over NFS.  Thus NFS
has the disadvantage that you waste disk space since you can't use
compressed fonts.  NFS has the advantage that it frees Linux memory
since with NFS there is no need to run xfs.  Thus the choice of xfs or
NFS can be seen as a tradeoff between disk space and memory space.

8) Fonts -- with Font Server

If you have decided to set your system up using the xfs font server,
Copy /usr/export/fsconfig to /usr/lib/X11/fs/config, and run xfs from
rc.local with the line:  (You should have already added this in Step 2.)

	/usr/bin/X11/xfs -config /usr/export/fsconfig &

The remainder of this step disables the NFS fonts.  This is only
necessary if you have been trying them out.  If you haven't, skip to
Step A below.

The file

	/usr/export/root/Xkernel.sun3/etc/fstab 

should not exist.  If it exists, rename it to

	/usr/export/root/Xkernel.sun3/etc/fstab-nfsfonts

Similarly, if the directory

	/usr/export/root/Xkernel.sun3/usr/lib/X11/fonts

exists, rename it to

	/usr/export/root/Xkernel.sun3/usr/lib/X11/fonts-nfsfonts

These actions disable the NFS font setup.

9) Fonts -- over NFS          (but Read 7 above and 9 below)

If you prefer, you can have your fonts served over NFS.  To do this,
you need to do the reverse procedure as that described at the end of
the section above.  i.e. you need to rename

	/usr/export/root/Xkernel.sun3/etc/fstab-nfsfonts
to
	/usr/export/root/Xkernel.sun3/etc/fstab

and rename

	/usr/export/root/Xkernel.sun3/usr/lib/X11/fonts-nfsfonts
to
	/usr/export/root/Xkernel.sun3/usr/lib/X11/fonts

You do not need to run /usr/bin/X11/xfs from your rc.local.

When you next boot the Sun3, its init script will notice the presence
of fstab and thus nfs mount the font directory.  It will also notice the
subdirectories of /usr/export/root/Xkernel.sun3/usr/lib/X11/fonts and
use NFS for fonts instead of the font server.

If you currently have compressed fonts, you need to uncompress them to
get an NFS font Xkernel to work.  To do this you need to go into each
font directory, uncompress any .Z files that may be there with the
command "gzip -d *.Z", and then rerun mkfontdir in that directory.
You can check if you have compressed fonts by looking in your font
directories to see if there are any .Z's in there.  (Note: It is
possible that compressed fonts are using gzip instead of compress
these days.  If so, they would end in .gz, not .Z.  In this case,
substitute .gz for .Z above.)

A) Testing it.

First, reboot linux so all the above changes can take effect.  As you
reboot linux, turn your diskless Sun3/Sun4c on.  After linux finishes
booting, your Sun3/Sun4c should boot and you should get a login screen.
(Assuming that you have configured your Sun3/Sun4c to autoboot from
the network using the monitor.)

However, it is also likely with this many things to set up that
something is wrong.  You will have to debug it.  For a Sun3, look at
Step A-Sun3.  For a Sun4c, look at Step A-Sun4c.

A-Sun3) Booting a Sun3.

At each step of the Sun3's boot, you should get messages on the Sun3
screen that show you what is happening.  For your reference, here are
the boot messages on my Sun3.  I have included comments on the right.
These comments should help you greatly in figuring out what's wrong
with your setup.

Note that if you get a failure early in this sequence, a problem with
improper network software configuration is as likely or more likely
than the possible problems listed here.  Check your interface
configuration, your routes, etc.

***********************************************************************

Auto Boot in progress...
Requesting Internet address for 8:0:20:0:c6:0
Using IP Address 1.2.3.5 = 01020305                    If it gets here,
                                                       RARP works.
Boot: le(0,0,0)
Booting from tftp server at 1.2.3.4 = 01020304
Downloaded 101800 bytes from tftp server.              If it gets here,
                                                       tftpd works.
Using IP Address 1.2.3.5 = 01020305
hostname: xhost
domainname: (none)                                     If it gets here,
server name 'server'                                   bootparamd works.
root pathname '/usr/export/root/Xkernel.sun3'
root on server:/usr/export/root/Xkernel.sun3 fstype nfs
Boot: vmunix
Size: 378560+90024+64936 bytes                        This may look slightly
                                                      different and print
                                                      out some error stats.
                                                      No big deal if it does.

SunOS Release 4.1.1_U1 ...
...                                                   
... (Lots of normal boot messages)                    
...                                                   
...                                                   
...                                                   
...                                                   
...                                                   
...
/sbin/init is running                                 If it gets here,
                                                      nfsd works.

sh: /etc/ifconfig_cmd.*: not found                    Normal.  Ignore.
Binding Unix socket: No such file or directory        Normal.  Ignore.

************************************************************************

Now, X should start up.  If you don't get a login screen, check for
xdm problems.


A-Sun4c)

Sun4c's print the following during a normal boot to Xkernel:

Booting from: le(0,0,0)vmunix
1ee00 Using IP Address 1.2.3.7 = 01020307
hostname: xhost-sparc
domainname: (none)
server name: 'server'
root pathname: '/usr/export/root/Xkernel.sun4c'
root on server:/usr/export/root/Xkernel.sun4c fstye nfs
size: 851968+147520+46256 bytes
SunOS Release 4.1.3 (Xkernel) #5: Sun Oct 17 02:29:37 EDT 1993
Copyright (c) 1983-1992, Sun Microsystems, Inc.
mem = 8192K
avail mem = 6922240
ethernet address = 8:0:20:3:6:d0
cpu = Sun 4/20
zs0 at obio 0xf1000000 pri 12
zs1 at obio 0xf0000000 pri 12
sbus0 at SBus slot 0 0x0
dma0 at SBus slot 0 0x400000
esp0 at SBus slot 0 0x800000 pri 3
esp0: Warning- non devices found for this SCSI bus
le0 at SBus slot 0 0xC00000 pri 5
bwtwo0 at SBus slot 3 0x0 pri 7
hostname: xhost-sparc
domainname: (none)
root on server:/usr/export/root/Xkernel.sun4c fstype nfs
swap on ns0b fstype spec size 6576K
dump on ns0b fstype spec size 6564K
/sbin/init is running
sh: /etc/ifconfig_cmd.*: not found
Binding Unix Socket: no such file or directory
PexExtensionInit: Couldn't open default PEX font file Roman_M

at this point, X starts, and you get an xdm login window.

Here are some of the things that can go wrong and their symptoms:

If you don't have an ethernet cable connected to your Sun4 correctly,
you get no messages at all after "Booting from: le(0,0,0)vmunix".  
It just sits there.

If the ethernet cable is connected correctly but there is no RARP server
answering, you get the message "Timeout waiting for ARP/RARP packet".

If the RARP packet is received correctly, but Linux doesn't have a
tftp server running *or* there is no arp entry for the Sun4, you get
no message for a long time, and then you get "receive failed" and
"Boot load failed".  I have modified the tftpd that comes with the
package to print debug messages to the syslog daemon.  Check to see if
you are seeing them on your console and/or xconsole.  The file
/etc/syslog.conf should have a line like this so that you can see
these messages:

*.*     /dev/console

If you see messages from tftpd, see what they say.  If they indicate
the correct file is found and is being sent back to the Sun4, check
out the arp entries.  You can print them with "arp -a" or "cat
/proc/net/arp".  If tftp can't find the correct file, it will print
the file name that is being requested.  Perhaps you haven't
established your file links correctly as described under the section
on setting up tftpd.  If you forgot to compile tftpd, you will see a
message from inetd that says something like this:

error: cannot execute /usr/export/src/tftp/tftpd: no such file or directory

If you get no messages at all, check that you correctly changed
/etc/inetd.conf.

If you get past that point, you may get the message "No bootparam
server responding; still trying".  If you get it, make sure that
rcp.bootparamd is running.  If you have changed your host name for the
Sun4 from xhost-sparc to anything else, this message can be caused by
a mismatch between the host name in /usr/export/bootparams and one of
the hosts files, /etc/hosts or /usr/export/root/Xkernel.sun4c/etc/hosts.  
If the hosts files have domain names added, the bootparams file
probably needs them too.  Case should probably match exactly.

If you get the error "Remote mount daemon not responding", rpc.mountd
isn't running.  Start it.  If you get the error "NFS server server not
responding, still trying", rpc.nfsd isn't running.  If you get
messages that indicate you can't mount root, check that you have
/etc/exports set correctly.  If you get messages about failures
running /sbin/init ("Init died") or if it stops right where it should say
"/sbin/init is running", try a different version of the NFS server.
The version included with the package should work.  Newer versions may
or may not work.  If you want to get a newer version to work that
fails here, try changing the mount permissions in /etc/exports from
read-only (ro) to read-write (rw).

So, that's it.  Bug fixes and comments to the address below.  Please don't
expect extensive support.  :-)

--Ross Martin
martin@kaveri.eas.asu.edu




