
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
over an ethernet cable connected to your Linux machine.  When it is
all properly installed, the Sun3 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.  Linux Xkernel may eventually be merged back
into Xkernel-2.0.  Most of the differences are slight, except for the
Sun3 kernel patch and the automated install.  If someone wants to work
on adding Linux to Seth's automated install, let me know.  The Sun3
kernel patch will eventually become unnecessary once the bugs in
fragmentation are fixed in the kernel.


WHAT YOU NEED

In addition to this package, you will need to be running a Linux
kernel version of 1.1.12 or later, 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
programs of net-0.32d or later, and you must set up your networking
properly (read the FAQ's and HOWTO's).

Before you even think about installing Xkernel, it is essential that
you get the appropriate kernel version and 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.  If you prefer, you can extract it elsewhere and make a
symbolic link from /usr/export to wherever you extracted it.


INSTALLATION

After the new kernel is installed, the networking code is properly
setup, and the code 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...)

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
169.146.39.135 for my Linux PC and 169.146.39.58 for my Sun3, so you
will see these numbers as examples below.  However, DON'T use these!
:-) Get your own.  Now that you have an IP number, add it to
/etc/hosts with a line as follows:

	169.146.39.58 xhost

Also in /etc/hosts, add the name "server" to the end of the list of
names for your Linux machine.  This specifies which machine will be the
NFS server for the Sun3.

In addition, change the addresses in the file
/usr/export/root/Xkernel.sun3/etc/hosts to match those of your Sun3
(xhost) 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 from net-0.32d as
/sbin/rarp.  Check this.  If it is not installed, install it.

Next determine the ethernet number of your Sun3.  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 /etc/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.

3) Setting up tftpd.

Compile tftpd from the source in /usr/export/src/tftpd.  Install the
result as /usr/etc/in.tftpd.  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 this:

	tftp    dgram   udp     wait    root    /usr/etc/tcpd   in.tftpd


( Note: It is doubtful that you use tftpd for anything else, but if
you do you should note that this tftpd is modified to add
"/usr/export/tftpboot/" to the beginning of any requested files.  This
enhances security and allows tftpd to work with a Sun3.  Other than
this modification, the tftpd included here is the standard Linux
tftpd. )

Next, change the internet address of the Sun3 to hexadecimal.  For
example, for my Sun3 which I have set up with IP number 169.146.39.58,
I convert to hex as follws: 169 is $A9 in hex, 146 is $92, 39 is $27,
and 58 is $3A.  So altogether, the internet address in hex is
A992273A. Then do (replacing the number with yours)
   
	cd /usr/export/tftpboot ; ln -s boot.sun3.sunos.4.1.1 A992273A

4) Setting up bootparamd.

Compile portmap and bootparamd from the source in
/usr/export/src/portmap and /usr/export/src/bootparamd.  Install the
results as /usr/etc/rpc.portmap and /usr/etc/rpc.bootparamd.  In order
to compile these, you may first need to compile and install rpcgen
from /usr/export/src/rpcgen.

The config file /usr/export/bootparams needs to be copied to /etc/.
(If you already have a /etc/bootparams file, you will probably need to
merge the two manually.)  Finally, check your startup scripts to make
sure that rpc.portmap is run at startup followed by rpc.bootparamd.

5) Setting up nfsd.

You need to compile and install the latest nfsd.  Currently this is
version 2.0.  To compile and install this do

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

After upgrading nfsd, copy (or merge) the file /usr/export/exports to
the file /etc/exports.

Check that rpc.nfsd and rpc.mountd are run from your startup scripts.
They should be run after rpc.portmap.

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.  XFree86 2.0
is also shipped with two xdm's, one for those who use shadow passwords
and one for those who don't.  You should make sure that
/usr/bin/X11/xdm is a link to the right one or perhaps is a script
that runs the right one.

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 will have
to add to /usr/lib/X11/xdm/Xaccess at the top the line

	xhost

This tells xdm that the host "xhost" is allowed to connect to your
Linux machine.

You will need to run xdm every time your system is booted, in order to
serve the Sun3 X terminal.  So 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.

Note: The remainder of this step describes possible setup you probably
don't want to do right away.  Leave this until after you have Xkernel
working with the default xdm files, if you try it at all.  At this
point you can skip to the next step, unless you are missing the files
in /usr/lib/X11/xdm/.  If you are missing them, you will need to get
some from somewhere.  Perhaps the easiest way is to follow the
instructions below.

If you are interested in an example xdm setup, I have included one in
/usr/export/src/xdm-setup.  This is an example of all files that need
to be put in /usr/lib/X11/xdm.  You should note that there are some
additional things you need before you can use this setup.  First, you
need to add a new user with user ID "halt", password "halt", and shell
/bin/false.  This is meant for shutting down the machine.  It nicely
checks to make sure no one else is logged on before rebooting.
Second, you need to install the "fortune" program (binary needs to be
in /usr/games/bin).  This is used to display a fortune for each new
login.  Third, you need to install "xmessage", to display the fortunes
and to display /etc/motd.  Fourth, you need to compile
xdm-login-accounting.  This is used to make sure users with invalid
shells can't log in under X and to add users who log in under X to the
utmp files so that they can be seen with the "last" command, etc.  On
my system this compile line works: (remove the -lshadow if you aren't
using shadow passwords)

	gcc -o xdm-login-accounting -lshadow xdm-login-accounting.c \
	    -I/usr/include

Fifth, you need to move the files in /usr/lib/X11/xdm elsewhere and
copy the files in /usr/export/src/xdm-setup to /usr/lib/X11/xdm.

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

With fonts you have a choice of how you want to set things up.  NFS is
the default, since it can be set up so that it will work in some cases
without user installation.  If you have font troubles or are low on
disk space, though, you may want to switch to the font server, since
it has advantages in ease of getting it working when there is trouble
and in using compressed fonts.

Compressed fonts cannot be used with the Sun3 Xsun over NFS.  (I
assume they can be used with the font server, but as of this moment I
have not actually tried it.)  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 fs.  Thus the choice of fs 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 fs font server,
Copy /usr/export/fsconfig to /usr/lib/X11/fs/config, and run fs from
rc.local with the line

	/usr/bin/X11/fs &

Then check that the file /usr/export/root/Xkernel.sun3/etc/fstab does
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
section 7 above.  i.e. you need to make sure that the files are set up
like they would normally be distributed:
/usr/export/root/Xkernel.sun3/etc/fstab exists and
/usr/export/root/Xkernel.sun3/usr/lib/X11/fonts exists, and they have
their original distributed contents.  You may need to rename
/usr/export/root/Xkernel.sun3/etc/fstab-nfsfonts and
/usr/export/root/Xkernel.sun3/usr/lib/X11/fonts-nfsfonts to the
names above.

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 on.  After linux finishes
booting, your Sun3 should boot and you should get a login screen.
However, it is also likely with this many things to set up that
something is wrong.  You will have to debug it.

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 169.146.39.58 = A992273A              If it gets here,
                                                       RARP works.
Boot: le(0,0,0)
Booting from tftp server at 169.146.39.135 = A9922787
Downloaded 101800 bytes from tftp server.              If it gets here,
                                                       tftpd works.
Using IP Address 169.146.39.58 = A992273A
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.

So, that's it.  Bug fixes and comments to the address below; problems
to /dev/null.

i.e. If you have problems with this package, don't ask me to give you
email support.  I'm not paid for this.  Fix your problems yourself.
Consider it a learning experience.  When you find what's wrong, send
me a note so I can fix the package or add a warning to others in the
next version.

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




