.TH USAGE 8
.SH NAME
usage \- installing and using Minix
.SH DESCRIPTION
.de SP
.if t .sp 0.4
.if n .sp
..
.de XB	\" An example in bold print.
.RS
.nf
.ft B
\&\\$1
.ft R
.fi
.RE
..
This manual page describes the installation and use of Minix from a
System Administrators point of view.  It contains an installation guide,
instructions on how to do the initial configuration and some other info.
More detailed information can be found in
.BR boot (8)
and
.BR hier (7).
.SS Requirements
The minimum system Minix can be installed on comfortably is an IBM PC/AT
or PS/2 with a 286 processor, 2 Mb memory, a 720 kb diskette drive, and 30
Mb free space on an AT,
.ig
PS/2,
..
ESDI, or \s-2SCSI\s+2 hard disk (the latter
controlled by an Adaptec 1540A.)  Minix-386 can be installed on a machine
with at least a 386sx processor and 3 Mb memory.
.SS Installation
You can install Minix automatically or manually as described in the sections
below.  The end result is the same, but manual installation allows
you to deviate from the preconfigured choices.  You may wish to read the
manual pages of the programs used below before you start.  You may especially
want to read
.BR boot (8)
if your machine is not a standard AT clone, because you may need to set a
few boot parameters to configure drivers.  To do this type
.B ESC
to get to the Boot Monitor prompt, set the appropriate variables, use
.B save
to store the settings and
.B menu
to continue where you left off.
.PP
To install the system you need two diskettes: a bootable root diskette and a
diskette full of binaries to use as
.BR /usr .
Let's call these diskettes
.B \s-2ROOT\s+2
and
.BR \s-2USR\s+2 .
These two diskettes may also be combined on a single high density diskette.
In that case the \s-2USR\s+2 part is on the
.B c
partition.
.PP
Insert the \s-2ROOT\s+2 diskette, boot the machine and type '=' to the menu.
The Minix kernel is loaded and takes control when you see the copyright
banner.  After loading the root diskette into RAM you will be asked to
finish the name of the device to mount on
.BR /usr .
Remove \s-2ROOT\s+2, insert \s-2USR\s+2 and answer the question with
.BR fd0 ,
the name of floppy disk 0, or
.BR fd0c
for a combined diskette.  Login as
.BR root .
.SS "Automatic Installation"
Type
.B instdist
to start the installation script.  
The first thing to do is to make a partition, for this you are placed in a
partition table editor named
.BR part .
This partition table editor is very easy to use (in authors opinion), but it
is also very easy to make a mess of your partition table real quick.  So if
you get into trouble type 'q' to quit, 'n' to not write the table, DEL to
stop the installation script and start over.  Use the '?' key to get help.
.PP
With the '+' and '\-' keys you can select the disk device to install on,
probably
.BR /dev/hd0 ,
the first hard disk.  The partition table will probably show a single MS-DOS
partition.  Do not touch it!  You only need to make one new partition, so
modify an entry marked "None".
.PP
The script then wants to know the name of the partition you've created, this
name is probably still visible on the screen (hd2, hd6, something like
that.)  The new partition table is reloaded into the driver, and the new
Minix partition is carved up into a 1440 kb root, 1440 kb scratch, and the
rest for /usr.
.PP
After making /usr, it is immediately put to use to replace the installation
/usr file system so that you can remove the \s-2USR\s+2 diskette and insert
the \s-2ROOT\s+2 diskette (unless they are one and the same).  The root file
system is filled with the contents of the \s-2ROOT\s+2 diskette and slightly
patched up to work on the hard disk (/etc/fstab.)
.PP
The last step is simple and boring.  You have to enter all the other
floppies in the proper order to fill /usr completely.
.PP
You can now skip the next section, but it may be instructive to read it
anyhow.
.SS "Manual Installation"
The instructions that follow are at a very low level and require you to be
very careful.  The big advantage is that you know precisely what
tools have been used and how everything works.  The disadvantage is that
you may easily make a mistake that either forces you start over if you are
lucky, or wipes out the contents of your hard disk if you are not.
.PP
Run
.B part
to make partitions to load the system into.  The best thing to do is to make
one large primary partition and to carve this partition up into three
subpartitions for the root, a scratch partition, and an
.B /usr
partition.  The assumption is that you will use the second partition on the
first hard disk,
.BR /dev/hd2 ,
and that
.BR hd2a ,
.B hd2b
and
.B hd2c
will be root, scratch and /usr.  If you want to use the first partition on
the second hard disk for instance, then substitute hd6 and hd6[a-c] for the
above.  On a \s-2SCSI\s+2 disk it will be /dev/sd2 for the second partition
on the disk at target 0.  See the section on devices below, and the manual
pages of
.BR part (8),
.BR hd (4),
and
.BR sd (4).
Start
.B part
and select the whole hard disk device (the "multiple of 5" device) that you
want to install Minix onto.  In our example it will be
.BR /dev/hd0 .
.PP
.B Part
is a bit dangerous to use, so be careful.  Only make a single partition in
the primary partition table, using an entry marked "None".  Then hit '>' on
this new partition to make a subpartition table.
.PP
For the root subpartition you need at least 720 kb for Minix-8086, Minix-386
needs at least a 1024 kb root.  You can make it larger if you want to, but
it is advisable to never let the contents outgrow a floppy.  (The
\s-2ROOT\s+2 diskette is a copy of a root file system, and will be used to
fill your root subpartition.)  The automatic installation uses 1440 kb, but
creates a file system that is smaller.
.PP
The second subpartition is the "scratch" partition, it can be used for
various things, most notably to test new experimental kernels.  1440 kb is
more than enough for scratch.
.PP
Use the rest of the partition for the /usr subpartition.
.PP
When you are done check that /dev/hd2a is active (the * after the partition
number) so you can boot from it later.
.PP
If your disk has bad blocks then don't put the root or scratch subpartition
on top of them.  Make sure the inode tables in the other partitions don't
have bad blocks either.  You can put the subpartitions out of order on disk
if that helps.  Subpartition tables, other then the main partition table, are
not sorted by the driver.
.PP
After making the partitions you do not have to reboot.  The disk driver
reloads the partition tables on the next access if the disk is not in use.
(Open or mounted.)
.PP
To be able to boot from /dev/hd2a you must place a master bootstrap in
/dev/hd2.  It has been placed there by
.B part
if it told you that it was creating a new partition table, but
.PP
.XB "installboot\0\-m\0/dev/hd2\0/usr/mdec/masterboot"
.RE
.PP
will put it there for sure.
.PP
You will start by making a file system for /usr and fill it partially.  This
may seem to be out of order, but you can't insert the \s-2ROOT\s+2 floppy
right now.
.PP
.XB "mkfs\0/dev/hd2c"
.XB "readall\0\-b\0/dev/hd2c | sh"
.XB "mount\0/dev/hd2c\0/mnt"
.XB "cpdir\0\-v\0/usr\0/mnt"
.PP
This will create a file system on /dev/hd2c, mount it on /mnt, and copy the
contents of the \s-2USR\s+2 floppy onto it.  The call to
.B readall
marks bad blocks on the file system as unusable, you can omit this on a
drive known to be spotless (\s-2IDE\s+2 or \s-2SCSI\s+2.)
.PP
You can now use the new /usr in place of the \s-2USR\s+2 floppy:
.PP
.XB "umount\0/dev/hd2c"
.XB "umount\0/dev/fd0"
.XB "mount\0/dev/hd2c\0/usr"
.PP
This little dance has freed up your floppy drive, so please remove the
\s-2USR\s+2 diskette and replace it by the \s-2ROOT\s+2 diskette.  Make a
file system for the root of at least 720 kb (1024 kb for Minix-386), and
fill it from the floppy:
.PP
.XB "mkfs\0\-i\0512\0/dev/hd2a\0720"
.XB "mount\0/dev/fd0\0/fd0"
.XB "mount\0/dev/hd2a\0/mnt"
.XB "cpdir\0\-v\0/fd0\0/mnt"
.XB "umount\0/dev/fd0"
.PP
Edit the file
.B /mnt/etc/fstab
to name the new devices.  It should look like this:
.PP
.XB "root=/dev/hd2a"
.XB "tmp=/dev/hd2b"
.XB "usr=/dev/hd2c"
.PP
Unmount the new root:
.PP
.XB "umount\0/dev/hd2a"
.PP
Make it bootable:
.PP
.XB "installboot\0\-d\0/dev/hd2a\0/usr/mdec/bootblock\0boot"
.PP
The automatic script would now set the
.B ramimagedev
boot variable.  You can do this now using the
.B edparams
command, or you can postpone it until the testing fase later.  The setting
should be:
.PP
.XB "ramimagedev=hd2a"
.PP
All that is left to do is to fill /usr.  Type these commands:
.PP
.XB "cd\0/usr"
.XB "vol\0720\0/dev/fd0 | zcat | tar\0xvfp\0\-"
.PP
And insert all the floppies one by one in the proper order.
.SS Testing
By now a binary Minix system is present on your hard disk.  Time to see if
it works.  Leave the \s-2ROOT\s+2 diskette in the drive and type
.BR reboot .
You are now going to use the power of the Boot Monitor on the diskette to
boot the Minix partition on the hard disk.  Hit
.B ESC
to get to the command mode, followed by
.B boot hd2
to boot the primary partition Minix has been installed in.  For a
\s-2SCSI\s+2 disk you will have to use a 'hd' name too.  The monitor uses
the BIOS, so you will have to treat it as a "normal" disk at this point.
.PP
The hard disk bootstrap is now showing the menu again.  You can type '='
to start Minix, but you probably want to change the boot parameters.
Hit
.B ESC
once more to get to the command prompt.  The command
.B set
shows what the current parameters are.  Here is an example that shows how
to make a menu to start Minix, start a test kernel, or boot MS-DOS:
.PP
.XB "minix(=,Minix)\0{boot}"
.XB "test(t,Test)\0{boot hd2b}"
.XB "dos(d,MS-DOS)\0{boot\0hd1}"
.XB "save"
.PP
MS-DOS is assumed to be in the first partition in the example above (hd1).
When finished type
.B menu
to see if the menu looks right.  If so hit '=' to start Minix.
.SS Names
A standalone machine will have to be given a name.  In
.B /etc/hostname.file
change
.B noname
into the name you want the machine to have.  Alas this file lives on the RAM
disk, so use these commands to copy it to less volatile storage:
.PP
.XB "M\0root"
.XB "cp\0/etc/hostname.file\0/root/etc"
.XB "U\0root"
.PP
.B M
and
.B U
scripts are quite useful to quickly mount a device.
.SS "Adding the Sources"
Type these commands to add the /usr/include, /usr/src, and /usr/man trees:
.PP
.XB "cd\0/usr"
.XB "vol\0720\0/dev/fd0 | zcat | tar\0xvfp\0\-"
.PP
And insert the source floppies one by one in the proper order.
.SS Active on Boot
You may want to make the Minix partition active so that it is automatically
booted.  With DOS
.B fdisk
or Minix
.BR part ,
mark the primary partition that contains Minix active.  Using the menu you
made earlier you can boot either Minix or DOS at a keypress.  You can even
set timeouts.  To boot Minix automatically after 5 seconds:
.PP
.XB "main()\0{trap\05000\0minix;\0menu}"
.PP
See
.BR monitor (8)
for all the details on the monitor.
.PP
If you don't trust this then you can rig up a diskette that boots the Minix
partition when left in the drive:
.PP
.XB "installboot\0\-m\02\0/dev/fd0\0/usr/mdec/masterboot"
.PP
The number 2 indicates the hard disk partition that must be booted, you can
use the numbers 1 to 9 for hd1 to hd9.
.SS Devices
A crash course on the Minix devices in
.BR /dev :
The two hard disks are named
.BR hd0
and
.BR hd5 .
These "multiple of five" devices address the entire hard disk, from the
first to the last byte.  Each disk has four partitions, for disk 0 they are
.BR hd1 ,
.BR hd2 ,
.BR hd3 ,
and
.BR hd4 .
And for disk 1 they are named
.BR hd6 ,
.BR hd7 ,
.BR hd8 ,
and
.BR hd9 .
These partitions may contain file systems,
.B hd1
often contains the MS-DOS C: file system.  Minix can use these partitions
for file systems too, but you can also partition one of these "primary
partitions" into four so-called subpartitions.  The subpartitions of
.B hd1
are named
.BR hd1a ,
.BR hd1b ,
.BR hd1c ,
and
.BR hd1d .
The other partitions may have four subpartitions that are named in the same
way by adding a letter from
.B a
to
.BR d .
So one disk may have four partititions, and 16 subpartititions total.  SCSI
disks are named in the same way, from
.BR sd0
to
.BR sd39d
for all possible devices for all eight SCSI targets.
The two floppy disks are
.BR fd0
and
.BR fd1 .
Each may have four partitions named
.BR fd0a ,
.BR fd0b ", ..."
.BR fd1d .
The command
.B MAKEDEV
knows how to make devices, and
.B DESCRIBE
can tell you what an unknown device may be, or even what all devices in
.B /dev
may be if called without arguments.
.SS Editors
The editors available are
.B elvis
(a
.B vi
clone),
.B elle
(a simple
.B emacs
clone),
and the old Minix
.B mined
editor.  Of these editors only elvis can recover your file after a system
crash.  Only
.B mined
is available at installation time.  (All you need to know about mined right
now is that CTRL-X gets you out of it.)
.SS "Installing on a \s-2SCSI\s+2 disk"
Using a disk other than a
.B hd
disk complicates things a bit.  The Boot Monitor uses the BIOS, so it names
all disks with
.B hd
names.  So it is
.B boot hd1
to boot partition 1, and
.B "ramimagedev=sd2a"
to tell Minix its root partition.  If you have both a normal and a SCSI disk
then the disks may be
.B hd0
and
.B hd5
to the Monitor, and
.B hd0
and
.B sd0
to Minix.
.SS "National keyboards"
The directory
.B /usr/lib/keymaps
contains keymap tables for several national keyboards.  If you have a German
keyboard for instance, then
.PP
.XB "loadkeys\0/usr/lib/keymaps/german.map"
.PP
will load the German key translation table into the keyboard driver.  Copy
the map to
.B /etc/keymap
once Minix is installed on the hard disk, because having to type one of
these
.PP
.XB "loadkezs\0\-usr\-lib\-kezmaps\-german.map"
.XB "loqdkeys\0=usr=lib=key,qps=french.,qp"
.PP
on a reboot gets a bit annoying after a while.  Send corrections and new
keymaps to the person named below.  (Do not send a Dutch keymap, buy
yourself a real keyboard instead.)
.SH SUGGESTIONS
Below are a few useful suggestions.  Some of the information can be of use
in other situations then described here.
.SS "Low on memory"
The normal installation requires that you have enough memory for a large RAM
disk.  You can still install Minix normally if you either have a high density
diskette drive for a combined root+usr floppy, or you have two floppy drives
of at least 720 kb.  Before booting you have to set the variable
.B rootdev
to the same value as
.BR ramimagedev .
This is slower then a RAM disk, but saves a lot of memory.  Minix-386 may
still run quite well without a RAM disk due to its larger block cache.  You
may wish to run Minix-386 like this always to get rid of the nuisance of
having to copy files from the RAM disk to the hard disk all the time.
.PP
The automatic installation script knows how to handle this new situation.
If you install manually then you have to use
.PP
.XB "cpdir\0\-vx\0/\0/mnt"
.PP
to copy the root device to disk.  When it is time to fill /usr and you only
have one floppy drive then hit DEL to get out of the installation script and
reboot as described in "Testing".  You can then finish the installation
manually.
.SS "Low on memory and/or using the BIOS disk driver"
If you only have one small disk drive, or you want to run Minix on an XT,
or you have to use the BIOS disk driver, then you can use the
\s-2TINYROOT\s+2 boot image.  This image contains a small kernel with only
the BIOS and XT disk drivers, and a small root file system.  You can use
this disk to boot your machine.  Use the normal \s-2ROOT\s+2 to install the
root file system.  Keep booting your machine with \s-2TINYROOT\s+2 until you
have recompiled a small kernel for your system.  Use the
.B rootdev
boot variable to select the hard disk root file system.
.SS "Floppy drive 1 is a high density drive"
If you would like to install from floppy drive 1 than you need to copy at
least one sector from the \s-2USR\s+2 image onto a diskette for drive 0.
The \s-2USR\s+2 bootstrap has been rigged to boot the other drive.
.SS "Installing on a second disk"
Minix doesn't care if it is installed on the second disk of a system with
two disks.  The only problem is to get it booted.  You can either rig up
a diskette to boot Minix as shown earlier, or you can use the same trick
on the the first disk.  The command
.PP
.XB "installboot\0\-m\05\0/dev/hd0\0/usr/mdec/masterboot"
.PP
will lock the first disk into booting the second disk.  Note that this
command modifies the disk outside a Minix partition, overwriting a bit of
code that has likely been put there by DOS fdisk.  First verify that the
Boot Monitor can boot a DOS partition, because then the Minix master
bootstrap can do it too.
.SS "Lots of memory"
You will have a hard time to make Minix run out of 3 Mb memory.  Memory you
can spare can be added to the RAM disk by setting the
.B ramsize
boot variable.  Add a few commands to
.B /etc/rc
to copy bits from
.B /usr
to the RAM disk, compiler passes and libraries for instance, and things will
suddenly run a lot faster.  Note that Minix-386 can run vary large
processes, so you don't want to enlarge its RAM disk, you may not even want
to have a RAM disk.  Instead you can enlarge its file system block cache,
one of the
.B NR_BUFS
definitions in <minix/config.h>.  One megabyte is enough to keep all
compiler passes in memory.
.SH SYSTEM ADMINISTRATION
The system has been set up with the idea that working as root is a bad thing
to do.  As root you are in no way protected from doing stupid things.  So
don't do development as root, work as
.BR bin !
Only in exceptional cases do you want to become root.  Being root is fun for
wannabe hackers, administrators know better.
.PP
To make life easier for bin, some programs like
.BR su (1),
.BR install (1)
and
.BR shutdown (8)
treat bin and other members of the operator group as special and allow them
the privileges of root.  (One is an operator if ones
group id is zero.)
.PP
The home directory of bin contains one important Makefile.  You can use it
to recompile all the commands and libraries of the system.  Type
.B make
to see the usage message.  If you want to compile just one command then you
can simply type
.B make
to do so.  To put it in its proper place you may have to type
.BR "make install" .
Read the Makefiles in the
.B commands
and
.B lib
subdirectories to understand how everything is put together.  If you are
tight on memory then
.B make
may fail to traverse down the source tree and also compile things.  You will
have to type
.B make
in each subdirectory.  You can run make in /usr/src at the end to see if
you've missed something or not.
.PP
The login shell of bin is
.BR ash ,
the BSD shell.  It has been modified to offer simple line editing using the
.BR editline (3)
library.
.B Ash
is rather big, so you may have to change bin's shell back to
.B /bin/sh
with
.BR chsh (1)
if you are low on memory.  Do not change root's shell to ash, and do not
replace /bin/sh by ash.  It may run out of memory at the wrong moment.
.PP
The kernel is not compiled from the master Makefile.  To make a new kernel
you have to step into the
.B tools
directory.  There you can run four different make commands:
.PP
.TP
.B make
This makes all the different kernel parts and combines them in the file
named
.BR image .
.TP
.B make fdboot
As above and then makes a boot floppy that you can use to restart your
system with.  You are prompted for the floppy device name.
.TP
.B make hdtest
This uses the scratch device instead of a floppy.  Testing a new kernel a
simple matter of choosing 't' on reboot.  If you made the menu shown in
"Testing", of course.
.TP
.B make hdinstall
Time to be careful.  If you are absolutely sure that the kernel works then
you can use this command to install it permanently.  This copies the file
.B image
to the file
.B /minix
on the root file system.
.PP
The first new kernel you would like to make is one configured for your
system.  The kernel you are running now contains several hard disk drivers
you don't need, and it does not have a TCP/IP server that you may want to
have.  In the file
.BR /usr/include/minix/config
you can find a number of
.BI ENABLE_ XXX
variables that can be set to
.B 0
to exclude, or
.B 1
to include a particular driver.
.PP
New additions to the system can be made in the
.B /usr/local
tree.  An empty directory tree has been set up for you and binaries and
manual pages are already in the search paths.  You can make a new user entry
simply by adding a password file entry, copying the contents of
.B /usr/ast
to the new home directory and to
.B chown -R
.IR user : group
it to the new owner.
.PP
The
.B TZ
variable in
.B /etc/profile
tells the time zone offset from the wall clock time to GMT.  You have to
change it for your time zone.  (See
.BR TZ (5).)
.PP
The function keys produce debug dumps, showing various interesting data
about the system:
.TP
F1 \- Process table
F1 produces a process table dump showing process-id's, memory sizes, and who
is waiting for what other process.
.TP
F2 \- Memory map
Like F1.
.TP
F3 \- Console scrolling
Select between hardware or software scrolling on the console.
.TP
F5 \- Ethernet stats
Shows number of packets send or received and other interesting data about the
ethernet adapter.
.TP
CTRL-F7 \- Quit
Sends a quit signal to all processes connected to the console.
.TP
CTRL-F8 \- Interrupt
Sends an interrupt signal.
.TP
CTRL-F9 \- Kill
Sends a kill signal.  If CTRL-F8 and CTRL-F7 don't get 'em, then this surely
will.  These keys are for disaster recovery.  You would normally use DEL and
CTRL-\e to send interrupt and quit signals.
.SH FILES
.TP 12
.B /usr/ast
Honorary home directory of Andew S. Tanenbaum.  Doubles as the place where
the default setup for a new user is found.
.SH "SEE ALSO"
.BR monitor (8),
.BR boot (8),
.BR part (8),
.BR mkfs (1),
.BR mount (8),
.BR M (8),
.BR fstab (5),
.BR hier (7),
.BR TZ (5),
.BR mkdist (8).
.br
"Operating Systems \- Design and Implementation" by Andrew S. Tanenbaum.
.SH BUGS
Except for the floppy driver none of the DMA based drivers know about DMA
being limited to a 24 bits address, i.e. the first 16 Mb.  So under Minix-386
you run a slight risk that a
.B tar
or
.B dd
command uses a buffer above 16 Mb for reading or writing to a character
device.  This only happens if the low 16 Mb is taken by some huge processes,
and you have more than 16 Mb, of course.
.PP
The
.B ps
command doesn't show any process names and arguments and is thus currently
useless.
.PP
The disk driver for the early model PS/2's has not been tested.  To make
sure that it does no harm it can only read if it works at all.  Writes have
been disabled.  If you want to run Minix on your PS/2 and the ESDI driver
doesn't work for you then volunteer as a guinea pig.
.SH AUTHOR
Kees J. Bot (kjb@cs.vu.nl)