ODDAS-LINUX INSTALLATION INSTRUCTIONS
-------------------------------------

Author:      Pete Buechler <peterb@suse.com>
Last update: 21 October 2000

1) Download the latest release from the project page at:

   http://sourceforge.net/projects/oddas/

2) Find a nice directory and untar and unzip the file there.

   tar xvfz oddas-linux-x.x.tar.gz

3) Make sure that you have a set of tools that target your embedded
   processor.

There are directions for building a set of cross-development tools at:

   http://www.objsw.com/CrossGCC/

I have prepared some packages for the i386 version of SuSE 6.4,
targeting the i386 (sic) and the PowerPC. These are at
ftp://ftp.suse.com/pub/people/peterb.

4) If you are going to boot off a hard drive or compact flash, proceed
to step 5. If you want the quick and easy turnaround that an NFS mounted
root partition allows, proceed through the lettered substeps below.

The NFS HOWTO is a good reference at this point,
http://www.linuxdoc.org/HOWTO/NFS-HOWTO.html.

a. Make sure your host's kernel is compiled with NFS server support.

b. Create a directory to be used as the root file system for the
embedded target. In my example it is /embedded/aaeon for my Aaeon
PCM-4335 board and /embedded/rpxlite for my Linux Planet PPC 823e
system. These will later be used as the targets for the build script,
"build_oddas_linux". They will be set in step 5.

c. Update your /etc/hosts file or DNS to include the addresses of the
embedded systems. For instance, I have the following lines in my
/etc/hosts file:

192.168.0.1     CX579290-B
192.168.0.3     rpxlite
192.168.0.4     aaeon

You will also have to put these into the /etc/hosts file in the
embedded system, see step 6f below.

d. Ensure your inetd is setup to allow tftp and bootp. These programs
should be on your system, plus they should be enabled in /etc/inetd.conf.
I have the following two lines in my inetd.conf:

tftp    dgram   udp     wait    root    /usr/sbin/tcpd	  in.tftpd -s /tftpboot
bootps	dgram	udp	wait	root	/usr/sbin/bootpd  bootpd -c /tftpboot

e. Create the /etc/boootptab file for bootpd. You will need to get the
hardware address of your ethernet controller and put it in place of
the ones that I have in the ha field in the example below. What you
can do is continue to follow these directions up to the point where
you boot up your kernel on your target with the support for your
ethernet card. If all is well, it will tell you the hardware address
when the driver detects the card. It will then fail, saying that it
cannot mount its root file system. Come in and fix this file, restart
the bootpd process and try again.

Here is my file, as an example:

.default:sa=host:hn:sm=255.255.255.0
rpxlite:ha=0010EC00109C:hd=/tftpboot:rp=/embedded/rpxlite:tc=.default
aaeon:ha=003059002f53:hd=/tftpboot:rp=/embedded/aaeon:tc=.default
  
f. Create or update /etc/exports to allow for NFS to export the file
systems as root file systems. My entire exports file follows:

# See exports(5) for a description.
# This file contains a list of all directories exported to other computers.
# It is used by rpc.nfsd and rpc.mountd.
 
/embedded/rpxlite rpxlite(rw,no_root_squash)
/embedded/aaeon aaeon(rw,no_root_squash)

g. Make sure that you have nfsd and mountd running. You will have to
restart them if they were already running before you updated the
configuration files above.

5) Edit the build configuration file, oddas.cfg.

This is located at the root of the oddas-linux tree. You need to
choose an architecture, a place to root the embedded system's file
tree, a place where the build will take place, the name of the
system that you will want any mail generated on the embedded system to
be routed to, and whether the system supports console on a serial port 
or with a virtual terminal.

A bit of explanation is in order for the fourth one. My theory is that
the system running embedded Linux may be rarely logged into directly.
It will just sit out there, taking care of business, without a lot of
day to day care required. But if it does need something, mail should
be generated. The mail is all forwarded to a mail hub, none of it
stays on the embedded system. That way, you can be e-mailed about any
problems that occur on the system.

6) Edit the configuration files that will be sitting in /etc on the
embedded system.

There are a lot of these, so I will break this point down further,
giving each file a letter. I have attempted to put reasonable values
in most of these, but there are some you will just HAVE to edit. I
will mark each with what I perceive as the likelihood of their having
to be changed. These will be found under the subdirectory
"other_files".

a. /etc/cron* - crontab probably OK for you, you will probably add
scripts to the cron subdirectories.

ODDAS-Linux comes with the Vixie cron daemon, but not the at daemon. I
figured that if you really need at, you could fake it with
cron. However, at is so small that I'll try to get it squeezed in for
the next release. Any how, the system cron table in /etc/crontab
should not be confused with the crontab command :-(. The former is the
file in etc/crontab and is documented in man 5 crontab, if you are
fortunate enough to have a desktop system which uses Vixie cron, as
does ODDAS-Linux (most desktop systems DO use Vixie). The user command
is also in ODDAS-Linxu and is documented by "man 1 crontab". The
system crontab is now set up to run a script named
/usr/lib/cron/run-crons, which runs the scripts in
/etc/cron.{hourly,daily,weekly,monthly} at that time interval. So
without knowing any more about crontabs you can place your own scripts
in there. Thus, I rate the chances of your having to change
etc/crontab as low, but you will probably want to put something into
the cron subdirectories. There are some scripts in the cron.daily
subdirectory already, to clean up core files, clean the tmp directory,
and to compress log files that have grown too large.

b. etc/fstab - good chance that you will want to edit this

This file is a standard UNIX file system table, as documented by "man
5 fstab". For development I mount the root file system using NFS,
which reduces the turnaround time on changes to the system. The
current fstab includes that line. For production, the root file system
will either be on a compact flash memory (which mounts like an IDE
drive), or an M-systems Disk on Chip (DOC). I have not yet used my
DOC, but I will. You will probably want to edit this file for your
hardware. The version now in the archive uses NFS mounting.

c. etc/ftpusers - probably will not need to edit this

This file describes the names of the users that may _*NOT*_ log into
the system via the FTP server. This usually includes "root", "uucp",
"news" and the like, because those users have too much power to be
allowed to do FTP. You probably will not need to change this file.

d. etc/group - should NOT edit by hand.

This file lists UNIX groups, as documented in "man 5 group". Since
your embedded system will be simple, you will probably not need any
more than are already in here. If you do, use the "addgroup" or
"delgroup" commands that come with ODDAS-Linux (it is a part of
busybox).

e. etc/host.conf - probably will not need to edit this

The file /etc/host.conf contains configuration information specific to
the resolver library. As long as your are happy to use a hosts file
for your embedded system, you will not need to alter this.

f. etc/hosts - you will need to change this

This file describes the hosts on your network. It is now set up for
the network in my house, so you will definitely need to change it. The
numbers now in the file are from the set reserved for private
networks, i.e., these numbers should never be on the Internet. Thus,
you COULD use the same numbers for your machines, if you wish.

g. etc/hosts.{allow,deny} - you will need to change this

These files are used by tcpd to determine if hosts are allowed to
access services. Currently only one host is allowed to access the
embedded system, by desktop machine. You will need to change this to
the name of YOUR desktop machine.

This security method is vulnerable to address spoofing attacks, but it
sure is small. Sigh. I'll be looking into putting ssh into ODDAS-Linux
instead of FTP and Telnet, in the future.

h. etc/inetd.conf - good chance that you will not change this

The file is currently set up to allow access to the embedded system
via FTP or Telnet, and to support http accesses as well. I suspect
that most people will want to keep this functionality.

i. etc/inittab - good chance that you will not change this

This is an inittab using the format that the busybox init
understands. It creates a single console, to save memory over the
standard six consoles.  You will probably want to leave this alone as
well, maybe toss in a second console :-). On bootup, the script
/sbin/init.d/rc is executed, on a three finger salute (CTRL-ALT-DEL) a
shutdown script is executed. These you can probably leave alone as
well, there are /sbin/init.d/halt.local and /sbin/init.d/rc.local
scripts that you can modify.

j. etc/modules.conf - you may want to change this

Right now this is just here for future use. If you know all about
modules and how to deal with them, change away. Otherwise, ignore.

k. etc/motd - you may want to change this

Perhaps you do not like my message of the day :-(

l. etc/nsswitch.conf - you probably will not need to change this

If you are happy to configure your embedded system with files then you
will not need to change this.

m. etc/passwd and etc/shadow - do not edit by hand

Change these using adduser, deluser, or passwd commands. Initially,
the root password is empty. Change that right away with the passwd
command!

n. etc/profile - you will probably need to change this.

This is the default shell script run when a user logs in. There is
some extra cruft in there now...

o. etc/protocols - you will probably not want to change this.

This file describes the various protocols that are available from the
TCP/IP subsystem.  It should be consulted instead of using the numbers
in the ARPA include files, or, worse, just guessing them.

p. etc/rc.config - you will need to change this

This contains config information used by the bootup scripts. You will
need to confirm at least the variables ROOT_FS_DEV, IP_ADDR, NETDEV_0,
and HOSTNAME.

q. etc/route.conf - you will probably want to change this

This file contains your static routing information. I just route
everything to my desktop system. Actually, maybe that will make you
happy too!

r. etc/securetty - probably will not want to change this

This file lists the tty devices which root can use to log on.

s. etc/services - probably will not want to change this

This file lists a heap of available TCP/IP services. I think you will
find any you need in there.

t. etc/ssmtp/ssmtp.conf - you will need to change this

The directory ssmtp contains the configuration file for the mail
server on the embedded system, which is ssmtp. This server assumes
that all mail is routed off the system. The documentation for this
file is in the package tarballs/ssmtp-2.38.tar.gz, but if you do not
want to get fancy there are probably enough comments in the file to
allow you to set it up without consulting the documents.

u. etc/syslog.conf - you will need to change this

You will need to change this because I now have remote logging to my
desktop machine enabled. Go in and change CX579290-B to the name of
your desktop machine. If you do that, all messages will be logged in
/var/log/messages on the embedded machine AND they will go to the
logger on your desktop. If you are really tight on disk space, comment
out the line sending messages to /var/log/messages.

v. etc/termcap - you will probably not need to change this

This contains the basic terminal types that you will probably want to
use on the machine (or emulate on your desktop connected via network).

7) Build the system.

You should now be able to go to the root of the ODDAS-Linux tree and
execute the script build_oddas_linux. You will need to be logged on as
root because the script copies device files, and on most systems you
must be root to create new special files.

8) Build the kernel that you wish to use.

There are just so many configuration options and different ways to use the Linux kernel that you will need to build your own here. I have included two example configuration files in this directory, aaeon.config and rpxlite.config, which I use for my two systems. These are the configurations that use NFS to mount root.

9) We have a bit of a branch here, depending upon how you want to boot
your embedded system. I cover IDE hard drive or compact flash under 9a,
NFS under 9b, and Disk on Chip under 9c.

a. Use this step for booting off an IDE drive, or compact flash with
the pins mapped to the IDE pins so that it looks like an IDE drive.
Your hardware may already have the mapping or there is an adapter board
available from http://www.tapr.org. For NFS mounted root, see 9b.

i) You will need to attach a floppy drive to your target system as
well as the hard drive. You will also need to obtain a rescue floppy,
either one you have built or one off the net (you can always remove the
floppy drive after ODDAS-Linux is installed). The rescue disk will need
utilities such as mke2fs, fdisk, lilo, tar, gzip, etc.

ii) Tar and gzip the root file system without the Linux kernel image. It
should fit on one floppy. Place the kernel image on a second floppy. To see
what goes into a typical kernel image for a PC/104 system, look at the file
aaeon.disk.config in this directory.

iii) Boot the target system using the rescue floppy.

iv) Use fdisk to partition the hard drive and mke2fs to create a file
system on it. Mount it under /mnt on your rescue system.

v) Copy the compressed root system from the first floppy to /mnt and 
uncompress and untar it there. Create a new directory, /mnt/boot, then 
copy the kernel from the second floppy to /mnt/boot. 

vi) Doublecheck the file /mnt/etc/lilo.conf.

vii) Run lilo with the command "/mnt/sbin/lilo -v -r /mnt".

viii) Make sure all floppies are out of the drive and reboot.

b. For mounting a remote root file system over NFS you must do
the following:

i) Hook up a standard floppy to your target system. I know, you will
not want it on your production system, but it makes life easy during
development.

ii) Make sure that you have the device file nfsroot in the /dev
directory of your oddas system. If not then use the command "mknod
/dev/nfsroot b 0 255".

iii) Compile the kernel with support for root over NFS. An example
configuration file is located at aaeon.nfs.config.

iv) Set the root file system of your kernel with the rdev
command. For example, if you are using bzImage as the name of your
kernel image, then the command would be "rdev bzImage /dev/nfsroot".

v) Copy the kernel image to a floppy. You can just use the dd
command: "dd if=bzImage of=/dev/fd0"

vi) Insert the floppy into the drive connected to your target system
and boot off it!

More information is available at:

http://www.linuxdoc.org/HOWTO/mini/NFS-Root-3.html

c. For booting from Disk on Chip I still have not gotten around to 
trying it, so you are on your own.

HAVE A LOT OF FUN!