.TH USAGE 8
.SH NAME
usage \- installing and using Minix-vmd
.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
..
.de 3A	\" Three Letter Acronym at 1 point size smaller.
\&\\$3\s-1\\$1\s+1\\$2
..
.de 3B	\" TLA in bold.
\&\\$3\fB\s-1\\$1\s+1\fR\\$2
..
This manual page describes the installation and use of Minix-vmd from a
System Administrators point of view.  It contains an installation guide,
instructions on how to do the initial configuration and some other info.
Please read this document entirely before attempting to install Minix-vmd.
The installation steps are in the proper order, but not all the information
you may need is presented at the right moment.  Other detailed information
can be found in
.BR boot (8)
and
.BR hier (7).
.SS Requirements
The minimum system Minix-vmd can be installed on comfortably is an
.3A "IBM PC/AT"
or
.3A PS /2
with a 386sx processor, 3 Mb memory, a high density diskette drive,
and 60 Mb free space on an
.3A AT ,
.3A ESDI ,
or
.3A SCSI
hard disk (the latter
controlled by an Adaptec 1540.)  You can recompile the kernel with this
setup, but not much else.  90 Mb would be better, it will give you some
space to breathe.  Installing X11 (30 Mb for the base system) will make this
disk small again and you will want to have at least 8 Mb memory to avoid
heavy swapping.
.SS "Minix-vmd installation background"
The objective of the installation is to create the six file systems that
Minix-vmd requires and to load the system into it.  Six file systems sounds
a bit much, but the default installation only creates three real file
systems, and fakes the remaining three by making them a part of one of
the other file systems using a so-called "loopback mount".  You could even
make just one file system and throw everything into it, but that's not
recommended.
.PP
For each real file system you need a disk, a primary partition on a disk,
or a subpartition within a primary partition.  Minix is quite flexible in
this regard.  Normally you would create three subpartitions within one
primary partition for the three file systems that you normally need.  We
will use the term "partition" as a generic term for the slice of disk used
for a file system.  Read the "Devices" section for more information on Minix
devices.
.PP
In this text we assume that Minix-vmd is installed in three subpartitions
in the second primary partition of the first hard disk.  It is easy to
deviate from this assumption while doing the installation, but in this text
it is necessary to assume what is the most common setup as an example.
This is the assumed setup:
.PP
.RS
.nf
.ta +\w'/usr/.lo/home   'u +\w'Mountpoint   'u +\w'Size (Mb)   'u
Device	Mountpoint	Size (Mb)	Function
.in +\w'D'u
/dev/hd2a	/	1.44	Root file system
/dev/hd2b	/tmp	1	Temporary files
	+swap	6	Swap space
/dev/hd2c	/usr	50	USR file system
/usr/.lo/var	/var	4	Variable data
/usr/.lo/opt	/opt	?	Optional packages
/usr/.lo/home	/home	?	Home directories
.in -\w'D'u
.DT
.fi
.RE
.PP
The sizes are minimum sizes for the minimum system mentioned in the
requirements.  For a machine with more memory and disk it is wise to choose
bigger sizes for the file systems.  Except for the root file system, it is
normally always 1.44 Mb, the size of a floppy.  Assuming a big enough disk
it is best to choose 4 Mb as the size of the file system for
temporary files,
.BR /tmp .
This is only for the /tmp file system.  The table above also shows an entry
for "swap space".  Minix-vmd allows one to create a file system smaller than
the partition it is put on and to use the rest of the partition for swap
space.  Any file system can share a partition with swap space, but one
normally uses the partition of /tmp for this.  One half for "temporary files",
and the other half for "temporary memory", together in one partition.
There should be enough swap space so that virtual memory
.3A RAM \& (
+ swap) is at
least 8 Mb.  That's enough to recompile the source tree.  As a rule of thumb
you could allocate as much swap space as you have
.3A RAM .
What you need
depends on the kind of use you have in mind.  If you plan to use
.B gcc
to compile large programs than you need at least 32 Mb virtual memory, and
even that may not be enough.
.PP
The
.B /usr
partition contains the main bulk of the Minix-vmd system.  It requires at
least 50 Mb for itself, and the space needed for the file systems that live
within it,
.BR /var ,
.BR /opt
and
.BR /home .
If /var is put on a partition of its own than it needs at least 4 Mb.  How
big /opt and /home must be depends on the sizes of the packages put in /opt,
and the requirements of the user home directories put in /home.  Note that
/opt and /home can be put in /var if /var has its own partition.  Or put
/var in /usr, /opt in a real partition and /home into /opt.  Any
combination is possible, but note that a loopback mounted file system locks
up a the real partition it lives on.  So the more important file systems
should be chosen first to be put on real partitions.  The table lists the
file systems in order of importance.
.PP
.B Important:
Don't loopback anything from /tmp.  The system will try to delete it at boot!
.PP
.B Limits:
The maximum file system size is 1 Gb.  The maximum number of files is 65535
per file system.  Minix-vmd can address a disk of up to 2 Tb in theory, but
we haven't had a chance yet to try a disk larger than 4 Gb, the point where
a 32-bit byte offset is about to overflow.  (Minix-vmd uses 64-bit byte
offsets and 32-bit block numbers within the file system code.)
.SS Installation
There are two ways to install Minix-vmd, semi-automatic and manually.  The
automatic method uses the
.B setup
installation script.  The manual method requires that you type all the
commands by hand.  The latter used to be the only way to install the system,
but the number of steps became so big that an installation script became
a necessity even for the author of this text.  The manual installation
section in this text is kept to give you an idea how it can be done, but you
are advised to run
.B setup
anyway.  This 500 line shell script monstrosity can do any kind
of installation that its author could imagine, so it will probably be able
to do your installation too.
.PP
To install the system you need two diskettes: a bootable root diskette and a
diskette full of binaries to use as
.BR /usr .
These diskettes are named
.3B ROOT
and
.3B USR .
These two diskettes may also be combined on a single 1.44 Mb diskette.
In that case the
.3B USR
part is on the
.B c
partition.
.PP
Insert the
.3B ROOT
diskette and boot the machine.  You will be greeted by a menu whose only
choice will be to boot Minix.  At this point you may want to type
.3B ESC
to reach the monitor prompt and set any so-called "boot variables" to
configure device drivers.
This is necessary if your machine is not a run of the mill kind of machine
that the majority buys.
In
.BR boot (8)
you can read all about the settings that each device driver understands.
When done type
.B menu
and type '=' to start Minix.
The Minix kernel is loaded and takes control when you see the copyright
banner.  After loading the root diskette into the
.3A RAM
disk you will be asked to finish the name of the device to mount on
.BR /usr .
Type
.BR fd0c
for a diskette that contains both
.3B ROOT
and
.3B USR ,
otherwise replace
.3B ROOT
by
.3B USR
and type
.BR fd0 .
Login as
.BR root .
.SS "Automatic installation"
Type
.B setup
to start the installation script.  It explains a few things, offers to
install a national keyboard map, etc.  Then you will be placed in the
partition table editor from hell named
.B part
to make all the necessary partitions needed for the real file systems.
Make sure all Minix partitions have type
.3A MINIX \&". \&"
Use the '>' key to make a
subpartition table inside a primary Minix partition.  The subpartition used
for the root file system must be marked active (the * next to the partition
number) so it can be booted later.  Don't activate any primary Minix
partitions (yet).
.PP
If your disk has bad blocks then don't place any partition containing the
root, /tmp, or any partition with swap space on top of them.  Make sure the
inode tables (the first 1%) in the other partitions don't have bad blocks
either.  You can put the subpartitions out of order on the disk if that
helps.  Subpartition tables, other than the main partition table, are not
sorted by the driver.  (It's nice to have root, /tmp and swap adjacent
though, so you can rearrange the three areas later if needed.)
.PP
Having survived
.B part
you are given the "current assumption" on how the file systems will be
created.  This assumption is initially the same as listed in the table
above.  If you want to change any file system designation then type the name
of that file system,
.BR / ,
.BR /tmp ,
.BR /usr ,
.BR /var ,
.BR /opt
or
.BR /home ,
and answer the questions that follow.  The first time you change a device
name to another subpartition all subpartitions are changed to the same
primary partition.  The rest is left to you.
.PP
You can rerun
.B part
by entering
.B p
instead of a file system name, or
.B q
if everything looks fine.  Next all file system will be created and
Minix-vmd will be copied from the floppies to the hard disk.  If you are
using two floppies to boot Minix-vmd you will be asked halfway to replace
.3B USR
by
.3B ROOT .
.PP
Eventually the script will finish with instructions on how to boot the new
system.  Please do so and move on to the "Testing" section, unless you feel
brave and wish to find out how it is done the hard way.
.SS "Manual installation"
This section describes the actions that
.B setup
performs to create a Minix-vmd system as per the default setup.
.PP
First run
.B part
to make the necessary file systems.  We assume that you have created the
file systems as in the default, otherwise modify the commands appropriately.
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
.B /dev/hd2a
later you must place a master bootstrap in
.BR /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
To migrate to disk you will first make a file system for /usr and fill it
partially.  This may seem to be out of order, but you can't insert the
.3B ROOT
floppy right now.
.PP
.XB "mkfs\0\-t\02f\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
.3B USR
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
.3A IDE \& (
or
.3A SCSI .)
.PP
You can now use the new /usr in place of the
.3B USR
floppy:
.PP
.XB "umount\0/mnt"
.XB "umount\0/usr"
.XB "mount\0/dev/hd2c\0/usr"
.PP
This little dance has freed up your floppy drive, so please remove the
.3B USR
diskette and replace it by the
.3B ROOT
diskette.  Copy the root to the hard disk:
.PP
.XB "mkfs\0\-t\02f\0/dev/hd2a"
.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/mnt"
.XB "umount\0/fd0"
.PP
Make it bootable:
.PP
.XB "installboot\0\-d\0/dev/hd2a\0/usr/mdec/bootblock\0boot"
.PP
The next steps are easier if you boot the new system now.  Type
.B halt
to get to the boot monitor prompt and type
.B boot hd2a
to start the new system.  Hit
.3B ESC
to get to the boot monitor prompt and type
.PP
.XB "rootdev=hd2a"
.PP
to tell Minix-vmd to use
.B hd2a
as the root file system, and not to fill the
.3A RAM
disk.  Type
.B save
to save, and
.B boot
to boot.  The /usr file system is now named
.BR hd2c .
Login as root.
.PP
The /tmp+swap device is the last real device to be initialized.  Assuming
that /tmp is to be 4 Mb large:
.PP
.XB "mkfs\0\-t\02f\0/dev/hd2b\04096"
.XB "mkfs\0\-t\0+swap\0/dev/hd2b"
.PP
Initialize the /var, /opt, and /home file systems, either by mkfs if they
live on their own partitions, or by creating directories for loopback
mounting as per the default setup:
.PP
.XB "mkdir\0\-p\0/usr/.lo/var"
.XB "mkdir\0\-p\0/usr/.lo/opt"
.XB "mkdir\0\-p\0/usr/.lo/home"
.PP
Fill in the proper names of the devices and loopback mounts in
.B /etc/fstab
to get file system checking and automatic mounting going.
All that is left is to initialize
.BR /var ,
that is supposed to contain a few directories and files.  The command
.B checkhier
will do this for you if you send its output into a shell:
.PP
.XB "checkhier | sh"
.PP
But you'll have to postpone this until you have installed /usr from
.3B USR.TGZ ,
because
.B checkhier
is not present yet.  (The
.B setup
script performes this task by itself.)
.PP
Type
.B halt
to stop the system and continue with the next section at the point where
.3B ESC
has been typed.
.SS Testing
By now a very small Minix-vmd system is present on your hard disk, equal
to what the
.3B ROOT
and
.3B USR
diskettes contain.  This is a good
time to test if you can get it booted.  Leave the
.3B ROOT
diskette in the drive and type
.B halt
to return to the Boot Monitor.  Use the monitor command
.B boot hd2
to boot the primary partition Minix has been installed in.  (If you need to
use
.B boot hd2a
to boot Minix then the master bootstrap in /dev/hd2 is somehow not working
or the first subpartition in /dev/hd2 is not active.)  For a
.3A SCSI
disk you will have to use a 'hd' name too.  The monitor uses the
.3A 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, hit
.3B ESC
once more to get to the command prompt.  The command
.B set
shows what the current parameters are.  You need to change the parameters so
that the root device is the disk partition itself and not the
.3A RAM
disk.  To save you work later it is wise to create a little menu and to
enable the second serial line.  (Only if you have no ethernet board on
.3A IRQ
3):
.PP
.XB "minix(=,Minix-vmd)\0{boot}"
.XB "dos(d,MS-DOS)\0{boot\0hd1}"
.XB "SERIAL1=on"
.XB "save"
.PP
.3A 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-vmd.
.SS Filling /usr
Type these commands to fill /usr from the
.3B USR.TGZ
floppy set:
.PP
.XB "cd\0/usr"
.XB "vol\0\fR[\fIsize\fR]\fB\0/dev/fd0 | gzcat | tar\0xvfp\0\-"
.PP
And insert all the floppies one by one in the proper order.  A floppy size
in kilobytes may be given if the images on the floppy are smaller than the
images themselves, e.g. 1200 kb images on 1440 kb floppies.
.PP
If
.3B USR.TGZ
is already present on the hard disk in an
.3A MS-DOS
partition, then this commands can be used to extract it to avoid the floppy
detour:
.PP
.XB "cd\0/usr"
.XB "mcopy\0hd1:USR.TGZ\0\- | gzcat | tar\0xvfp\0\-"
.PP
The file doesn't have to be in the root directory of
.BR hd1 ,
of course,
.B "hd6:/TMP/USR.TGZ"
would name a file on the first partition of the second hard disk in the
directory
.BR \eTMP .
.PP
The /usr file system can also be filled through a network from a remote host
if Minix-vmd is installed using the
.3B NETUSR
floppy instead of the normal
.3B USR .
Follow the instructions in
.BR boot (8)
to configure TCP/IP and boot Minix-vmd.  There are now two ways to fill
/usr.  One is to add the host name and login name of a remote host and a
remote user to
.BR /usr/src/.rhosts ,
as root, and to use the following command on the remote host:
.PP
.XB "rsh\0\-l\0root\0\fIminix-box\fP\0'cd\0/usr\0&&\0gzcat | tar\0xvfp\0\-'\0< USR.TGZ"
.PP
Two is to use
.B ftp
to copy the data directly from a Minix-vmd FTP site by using these commands
under Minix-vmd:
.PP
.XB "cd\0/usr"
.XB "ftp\0\-c\0\fIftp-site\fP:\fIdir\fP/USR.TGZ | gzcat | tar\0xvfp\0\-"
.PP
The sources may be installed using exactly the same commands, but with
.3B USR.TGZ
replaced by
.3B SRC.TGZ .
Note that this means that the sources must also be extracted relative to
.BR /usr .
.SS Active on Boot
You may want to make the Minix partition active so that it is automatically
booted.  With
.3A DOS
.B fdisk
or Minix
.BR part ,
mark the primary partition that contains the Minix root file system active.
Using the menu you made earlier you can boot either Minix or
.3A 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 or partition that must be booted, i.e.
.B /dev/hd2
in this example.
.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
.3A 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 partitions, and 16 subpartitions total.
.3A SCSI
disks are named in the same way, from
.BR sd0
to
.BR sd39d
for all possible devices for all eight
.3A 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
.3B MAKEDEV
knows how to make devices, and
.3B DESCRIBE
can tell you what an unknown device may be, or even what all devices in
.B /dev
may be if called without arguments.  Devices are described fully in
.BR dev (4),
and in device specific manual pages like
.BR fd (4)
and
.BR hd (4).
.SS "\s-1MS-DOS\s+1 virtual disks"
Minix-vmd has a special driver that allows one to use a very large
file on an
.3A "MS-DOS FAT"
file system as a Minix-vmd disk, see
.BR dosd (4).
If you don't have a partition available for Minix-vmd then you can do
the following:
.PP
Boot from
.3B ROOT
and specify the name of the
.3A DOS
file to use in the boot environment, e.g.
.PP
.XB "dosd0 = hd1:minix"
.PP
This is the file "minix" on what is likely to be your
.B C:
drive.  Before running
.B part
use
.PP
.XB "dd\0if=/dev/zero\0bs=1k\0count=80000 | mcopy\0\-\0hd1:MINIX"
.PP
to make a large file (in this case 80000 kb.)  With
.B "mdir hd1:"
you can tell if you have done it right.  Now you have a disk device
.B dosd0
available that you can partition and use.  There are no subpartitions
however, so you can only make a primary partition table.  (See
.BR dosd (4)
on why you should start partitions on even-numbered sectors.)  You can use
.B dosd1
for the root file system,
.B dosd2
for /tmp+swap, and
.B dosd3
for /usr for instance.  To boot this system you need a version of the boot
monitor that runs under
.3A MS-DOS .
This command will copy it to
.3A DOS :
.PP
.XB "mcopy\0/usr/mdec/dosboot.com\0hd1:BOOT.COM"
.PP
Under
.3A DOS
the command
.B "boot\0minix"
will then boot Minix from the virtual disk.  Don't forget to repeat the
.B "dosd0=hd1:minix"
setting.  Alas you need a spartan
.3A DOS
configuration for the monitor to work,
a 386 based memory manager doesn't allow a jump to protected mode.
.3A MS-DOS
6.0 and later have all kinds of tricks to change the way it is booted.
.SS "Virtual Disks"
The virtual disk driver allows one to concatenate two or more partitions
and/or disks to one disk device.  Ideal if you have two small disks that
Minix-vmd can't be installed on properly.  See
.BR vdisk.conf (5).
.PP
To use a virtual disk first create the necessary partitions when
.B setup
wants you to, then use the
.B s
command to start a subshell (or log in on another virtual console as root.)
Edit the file
.B /etc/vdisk.conf
and use the command
.PP
.XB "vdisk_ctrl\0\-c\0/etc/vdisk.conf"
.PP
to initialize the virtual disk.  Exit the shell with CTRL-D.  Do not change
any partitions anymore with
.B part
unless the virtual disk that depends on those partitions is disabled.
.SS Editors
The editors available are
.B elvis
(a
.B vi
clone),
.B joe
(a simple editor that can look like several editors, including emacs under
the name
.BR jmacs ),
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-1SCSI\s+1 disk"
Using a disk other than a
.B hd
disk complicates things a bit.  The Boot Monitor uses the
.3A BIOS ,
so it names all disks with
.B hd
names.  So it is
.B boot hd1
to boot partition 1, and
.B rootdev=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 "keymap\0\-l\0/usr/lib/keymaps/german.kbd"
.PP
will load the German key translation table into the keyboard driver.
.B Setup
will do this for you when you choose a keyboard type, and will create
a symlink
.B /etc/keymap
on the new root file system that points to the chosen keyboard table so that
it is loaded at boot.
.PP
Please send corrections and new keymaps to the person named below.  (Do not
send a Dutch keymap, buy yourself a real keyboard instead.)
.SS "Console Fonts"
Most of the keymaps make the keys emit ISO Latin-1 character codes.  The
console driver uses a crude translation table to map Latin-1 codes to the
IBM character set.  If you have an EGA or VGA card then you can choose one
of the font tables in
.B /usr/lib/fonts
to give the console a proper font.  To load the Latin-1 font:
.PP
.XB "loadfont\0/usr/lib/fonts/iso1.fnt"
.PP
The default font can be set by symlinking or copying the chosen font to
.BR /etc/font .
It will then be automatically loaded at boot.
.SH SUGGESTIONS
Below are a few useful suggestions.  Some of the information can be of use
in other situations than described here.
.SS "Virtual Consoles"
Hold down the ALT key and press the left or right arrow key, F1, or F2.
This switches the console between two login sessions.  These two arrow keys,
a function key, the up arrow key and a write to the status line brings the
status line into view.  ALT-down-arrow removes the status line.  (All
virtual consoles sit in video memory, so an old mono adapter can't have more
than one console.)
.PP
The console implements the same escape sequences as the X11
.B xterm
program.  As terminal type
.B vs100
is used, one of the alternate names of
.BR xterm .
When necessary one can also use
.BR xterm ,
.BR minix ,
.BR vt100 ,
or
.BR ansi .
.PP
Note that kernel messages, including function key output, only appear on
the first console.  This may be confusing, but it keeps the other consoles
clean.
.SS "Low on memory"
The normal installation requires that you have enough memory for a large
.3A RAM
disk.  You can still install Minix-vmd on a machine with as little as 2 Mb
memory if it either has an 1.2 Mb diskette drive for a combined root+usr
floppy, or two floppy drives of at least 720 kb.
.PP
Several problems must now be solved:  There is not enough memory for a
.3A RAM
disk,
.3B ROOT
is too big to be combined with
.3B USR
on a 1.2 Mb diskette, and
.3B ROOT
does not have enough free space in its
.B /tmp
to use it directly as the root file system.  So instead of
.3B ROOT
we use a smaller floppy image named
.3B TINYROOT .
You still need
.3B ROOT
to boot the system and load the Minix-vmd kernel, because
.3B TINYROOT
doesn't contain a kernel to save the necessary space.  The recipe to install
Minix-vmd is now:  Boot the machine with
.3B ROOT ,
type
.3B ESC
and enter the following commands:
.PP
.XB "rootdev=bootdev"
.XB "delay=swap"
.XB "boot"
.PP
The Minix kernel is loaded and the Monitor asks that you insert the root
floppy.  Replace
.3B ROOT
by
.3B TINYROOT
(optionally combined with
.3B USR )
and hit a key to continue.  You can now install the system normally with
.BR setup .
When done type
.B halt
to return to the monitor.  Do not yet use a command like
.B "boot hd2a"
to try the new system, but replace
.3B TINYROOT
by
.3B ROOT
and type
.B exit
to reboot.  Again hit
.3B ESC
and type
.PP
.XB "rootdev=hd2a"
.XB "boot"
.PP
to boot the system on the hard disk.
.B Rootdev
must be set to the root file system of the newly installed Minix-vmd, for
.B hd2a
is just default used in this text.  Use the name of the new root file system
instead.  The reasons for these machinations is that since
.3B TINYROOT
doesn't have a kernel, no kernel is installed on the hard disk.  So let's
repair this omission.  Log in as
.B root
on the new system, mount
.3B ROOT
and copy the kernel image to its proper place:
.PP
.XB "mount\0/fd0"
.XB "cpdir\0\-v\0/fd0/minix\0/minix"
.PP
Use
.B /fd1
instead of
.B /fd0
if the floppy happens to be in the second drive.
.PP
The installation will take quite some time, because the floppy drive keeps
whirring to load, and reload
.B gunzip
to decompress the compressed installation executables.  The file system
cache is too small to prevent trashing.  Once installed the system may run
quite well, because having virtual memory makes the system run less constricted
than a standard Minix-386 installation.  Don't be afraid to enable the
TCP/IP server, anything except the kernel and the file system cache can be
swapped out if not in use.
.SS "Floppy drive 1 is a 1.44 Mb drive"
If you would like to install from floppy drive 1 then you need to copy at
least one sector from the
.3B USR
image onto a diskette for drive 0.  The
.3B USR
bootstrap has been rigged to boot the other drive.
.SS "Installing on a second hard 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 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
.3A DOS
fdisk.  First verify that the Boot Monitor can boot a
.3A DOS
partition, because then the Minix master bootstrap can do it too.
.PP
If the day comes that you want to repair the master bootstrap then you can
use
.B fdisk /mbr
under
.3B MS-DOS
6.0 or newer, or the
.B installboot
command shown above without the number
.B 5
to make the master bootstrap boot the active partition again as is normal.
.SS "Boot scripts and such"
Inspect
.B /etc/rc
and other rc files to understand how the system starts.
.B /usr/lib/crontab
and
.B /usr/etc/daily
are also interesting reading.
.SS "The X Window System"
The command
.PP
.XB "vol\0\fR[\fIsize\fR]\fB\0/dev/fd0 | pkgadd\0\-x\0\-\0XF86-3.1.1"
.PP
installs the X11 package.  Read
.BR startX (1)
after installation to know more about X11 under Minix.
.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, but 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, the home directory of root is also in
.BR /usr/src ,
unlike most
.3A UNIX
systems where root lives in /.  The programs
.BR su (1),
.BR install (1)
and
.BR shutdown (8)
treat bin and other members of the
.B operator
group as special and allow them the privileges of root.  (One is an operator
if any of the supplementary group ids is zero.)  Operators should share the
shadow password of root by having
.B ##root
in their password field.  This way they all have one face (password)
to the outside world, forming no greater security risk than root alone.
.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" .
Most Makefiles simply throw the result into the
.B bin
or
.B sbin
directories by default, so be careful when you update something important,
first make a copy.
To compile just one library file use
.B make CC=acc ARCH=i386
or
.B make CC=gcc ARCH=i386
to compile it for either the ACK or GNU C-compiler.  Better inspect the
makefiles so you understand what's happening.  (Expect lots of warnings
when compiling.  The compilers are configured to complain a lot, and not all
source files live up to their standards.)
.PP
The kernel is compiled using the
.BR build (8)
command.  There is not much left that can be user configured, the old
.B <minix/config.h>
is gone in favour of
.B <minix/cfg_*>
that contain no configurable parameters.  About the only interesting
parameter left among the Minix include files is
.3B NR_PROCS
in
.BR <minix/const.h> .
It defines the maximum number of processes the system can run at once.  FS
also has several of these
.3B NR_*
parameters.  In time all of these will become boot variables, or even
runtime variables.  The
.B config.h
file in the kernel directory contains settable parameters that allow some
drivers to be included or excluded.  You can win 100 kb or so by deleting
the unused drivers.  (Doesn't seem much, but kernel memory is locked, i.e.
it can't be swapped out if unused.)  The
.3B DMA_SECTORS
parameter is important if you use the
.3A ESDI
or
.3A BIOS
disk driver.  Increasing
.3A DMA_SECTORS
may improve disk throughput significantly, at the cost of
.3A DMA_SECTORS
kilobytes.  You can increase
.3B NR_CONSOLES
if you want to have more virtual consoles.  Having more consoles costs
little memory, because all the consoles are kept in video memory.  Scrolling
speed of the console will go down if more virtual consoles share the
available memory.  CGA cards have space for 8192 characters, EGA and VGA can
have 16384 characters.
.PP
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
with the
.B adduser
command.  Make all new home directories in
.BR /home .
You as a system administrator will want your login to be a member of the
.B operator
group, and you will want the same
.B "$PATH"
setting as
.B bin
has, with all the extra
.B sbin
directories full of commands for the administrator, see
.BR /usr/src/.ashrc .
You also want to have
.B ##root
in the password field of your password file entry, so edit
.B /etc/passwd
as root.
.PP
The author of this text uses three group zero names:
.BR root ,
.BR bin
and
.BR kjb .
The last is for personal programming and other things that have nothing to
do with Minix.  It also contains his X11 setup to work with the system, with
nice menus to easily pull up xterm windows as bin or root.  It is nice to have
a personal login as a base of operation.  You don't want to be
.B bin
and clutter up
.B /usr/src
with personal things, and you sure as hell don't want to be
.B root
longer than is absolutely necessary.
.PP
The
.B TZ
variable in
.B /etc/timeinfo
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
Electronic mail is sent by the
.B smail
transport agent.  The default setup allows local email and email sent over
TCP/IP to be delivered to or sent by users on the local machine.  There is
no extra configuration necessary, but take a peek at
.B /usr/lib/smail/config
anyway.
.PP
The function keys still produce debug dumps like in standard Minix, with
a few differences.  The first difference is that you have to hold down the
CTRL key when pressing a function key.  ^F1, ^F5, and ^F8 lists processes,
ethernet stats and virtual memory stats, which may be of use.  Read
.BR console (4)
to know all the details of the screen and keyboard.
.SS "System shutdown"
You can't just turn a Minix system off.  Minix must be told to flush the
modified data in the file system cache first.  The following
commands/keystrokes can be used to exit Minix properly:
.TP
.B shutdown
First alert all users and then all processes of the impending shutdown
then halt or reboot the system in one of various ways.  See
.BR shutdown (8).
.TP
.B reboot / halt
Alert all processes of the system shutdown then reboot or halt.
.TP
.3B CTRL\-ALT\-DEL
Halts the system by running
.BR "shutdown \-h now" .
.PP
Minix halts by returning to the Boot Monitor, Minix reboots by instructing
the monitor to reboot Minix.  (Minix is just a subprocess to the monitor.)
Either halt Minix and use monitor commands to escape Minix, or use
.B shutdown \-R
to reset the system.
.SH DIFFERENCES
Minix-vmd is upwards compatible to standard Minix created by Andrew S.
Tanenbaum.  Many changes have been made to increase the functionality of the
base system.  It is in many ways more useful, and in many ways uglier and
more convoluted than the original.  It is still remarkably like the normal
Minix, it still has the same "feel".
.PP
These are some of the differences with standard Minix, those marked with
(P) are by Philip Homburg (philip@cs.vu.nl), those marked with (K) by Kees
Bot (kjb@cs.vu.nl):
.PP
.RS
Virtual Memory and paging to disk is by far the most important addition.
There is no longer a need for
.BR chmem (1),
although the maximum heap size it sets is still used.  The value is rounded
up to 3 Mb and used as an upper limit on the memory use of a process.
Memory is used more efficiently and
.BR fork (2)
is done by page sharing. (P)
.SP
Two new file system types with long file names.  Fast automated checking of
file systems on bootup. (K)
.SP
Asynchronous I/O, VGA and keyboard drivers to support X11.  Patches to
XFree86 to make it run under Minix. (P)
.SP
Commands and utilities adapted from standard Minix and many free third party
utilities added.  Some "weird" Minix utilities are gone, some have been
replaced, some have been reimplemented. (K)
.SP
Undervalued slave work needed to make any system look like a system. (K)
.SP
Executable caching, inode caching, name-to-inode caching. (P)
.RE
.PP
The most important difference between standard Minix and Minix-vmd is not
an actual difference, but a difference in philosophy.  Minix is a simple
.3A UNIX -like
system that "fits in one students head", as Mr. Tanenbaum likes to put
it.  Minix-vmd is not driven by this goal.  Instead, its authors use it as a
playgarden for new ideas.  Old ideas like POSIX compliance and X11 are just
there to make life under Minix-vmd more bearable, but everything else is
fair game.  You have been warned.
.SH FILES
.TP 12
.B /usr/ast
Honorary home directory of Andrew 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 fstab (5),
.BR hier (7),
.BR console (4),
.BR dev (4),
.BR adduser (8),
.BR build (8),
.BR @build (8),
.BR cc (1),
.BR TZ (5),
.BR mtools (1),
.BR vdisk.conf (5),
.BR rhosts (5),
.BR smail (8),
.BR shutdown (8),
.BR intro (2).
.br
"Operating Systems \- Design and Implementation 2/e" by Andrew S. Tanenbaum
and Albert S. Woodhull.
.SH NOTES
The notation
.BI < file .h>
refers to a C language include file in /usr/include.
.SH BUGS
Probably many, easily recognized by the system going into a state of panic.
Often an assertion failed leaving a wealth of information on your screen (if
not running X11.)  After a reboot you can find this information in
.BR /usr/adm/log .
We would appreciate it if you would be so kind as to send the details, and
how to trigger the bug, to kjb@cs.vu.nl or philip@cs.vu.nl.  DO NOT send bug
reports to ast@cs.vu.nl, he doesn't want to know.
.SS "Known Bugs"
Bugs we know about, but haven't fixed yet:
.PP
The mail command is only halfway there.
.PP
Inetd offers no UDP services.  There is no way yet to probe for an incoming
UDP packet without actually reading it.
.PP
Running 'make clean' for Smail and Perl doesn't clean all.
.PP
Backwards compatibility for standard Minix network programs fails on the
.B uname()
library call that cannot find the node name of a Minix-vmd machine.  As a
kludge to fix this type
.RS
.XB "uname\0\-n\0> /etc/hostname.file"
.RE
or change
.B /usr/etc/rc
to do this at boot time.
.PP
Minix-vmd offers only Minix-vmd and not much else.  Other free
.3A UNIX -like
systems have all the good software to get real work done.
.SH AUTHOR
Kees J. Bot (kjb@cs.vu.nl)