usage - installing and using Minix-vmd

     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 boot(8) and hier(7).

     The minimum system Minix-vmd can be installed on comfortably  is  an  IBM
     PC/AT  or  PS/2  with  a  386sx  processor,  3  Mb memory, a high density
     diskette drive, and 60 Mb free space on an AT, ESDI, or  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.

  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.

     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.

     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:

          Device          Mountpoint   Size (Mb)   Function
           /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

     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, /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 (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 RAM.  What you  need  depends  on
     the  kind  of  use  you  have in mind.  If you plan to use gcc to compile
     large programs than you need at least 32 Mb virtual memory, and even that
     may not be enough.

     The /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, /var, /opt and /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.

     Important: Don't loopback anything from /tmp.  The  system  will  try  to
     delete it at boot!

     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.)

     There are two ways to install  Minix-vmd,  semi-automatic  and  manually.
     The  automatic  method  uses  the  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  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.

     To install the system you need two diskettes: a  bootable  root  diskette
     and  a  diskette  full  of  binaries to use as /usr.  These diskettes are
     named ROOT and USR.  These two diskettes may also be combined on a single
     1.44 Mb diskette.  In that case the USR part is on the c partition.

     Insert the 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 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  boot(8)  you  can read all about the settings that each device driver
     understands.  When done type 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 RAM disk you will  be  asked  to
     finish the name of the device to mount on /usr.  Type fd0c for a diskette
     that contains both ROOT and USR, otherwise replace ROOT by USR  and  type
     fd0.  Login as root.

  Automatic installation
     Type 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  part  to  make  all  the
     necessary  partitions  needed  for  the real file systems.  Make sure all
     Minix  partitions  have  type  "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).

     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.)

     Having survived 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, /, /tmp, /usr, /var,
     /opt or /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.

     You can rerun part by entering p instead of a file system name, or  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 USR
     by ROOT.

     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.

  Manual installation
     This section describes the actions that setup performs to create a Minix-
     vmd system as per the default setup.

     First run 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.)

     To be able to boot from /dev/hd2a later you must place a master bootstrap
     in /dev/hd2.  It has been placed there by part if it told you that it was
     creating a new partition table, but

          installboot -m /dev/hd2 /usr/mdec/masterboot

     will put it there for sure.

     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
     ROOT floppy right now.

          mkfs -t 2f /dev/hd2c
          readall -b /dev/hd2c | sh
          mount /dev/hd2c /mnt
          cpdir -v /usr /mnt

     This will create a file system on /dev/hd2c, mount it on /mnt,  and  copy
     the  contents  of  the USR floppy onto it.  The call to readall marks bad
     blocks on the file system as unusable; you can omit this on a drive known
     to be spotless (IDE or SCSI.)

     You can now use the new /usr in place of the USR floppy:

          umount /mnt
          umount /usr
          mount /dev/hd2c /usr

     This little dance has freed up your floppy drive, so  please  remove  the
     USR  diskette  and replace it by the ROOT diskette.  Copy the root to the
     hard disk:

          mkfs -t 2f /dev/hd2a
          mount /dev/fd0 /fd0
          mount /dev/hd2a /mnt
          cpdir -v /fd0 /mnt
          umount /mnt
          umount /fd0

     Make it bootable:

          installboot -d /dev/hd2a /usr/mdec/bootblock boot

     The next steps are easier if you boot the new system now.  Type  halt  to
     get  to  the  boot  monitor  prompt  and  type boot hd2a to start the new
     system.  Hit ESC to get to the boot monitor prompt and type


     to tell Minix-vmd to use hd2a as the root file system, and  not  to  fill
     the RAM disk.  Type save to save, and boot to boot.  The /usr file system
     is now named hd2c.  Login as root.

     The /tmp+swap device is the last real device to be initialized.  Assuming
     that /tmp is to be 4 Mb large:

          mkfs -t 2f /dev/hd2b 4096
          mkfs -t +swap /dev/hd2b

     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:

          mkdir -p /usr/.lo/var
          mkdir -p /usr/.lo/opt
          mkdir -p /usr/.lo/home

     Fill in the proper names of the devices and loopback mounts in /etc/fstab
     to  get  file  system checking and automatic mounting going.  All that is
     left is to initialize /var, that is supposed to contain a few directories
     and  files.   The  command checkhier will do this for you if you send its
     output into a shell:
          checkhier | sh

     But you'll have to postpone this  until  you  have  installed  /usr  from
     USR.TGZ,  because  checkhier  is  not  present  yet.   (The  setup script
     performes this task by itself.)

     Type halt to stop the system and continue with the next  section  at  the
     point where ESC has been typed.

     By now a very small Minix-vmd system is present on your hard disk,  equal
     to  what the ROOT and USR diskettes contain.  This is a good time to test
     if you can get it booted.  Leave the ROOT diskette in the drive and  type
     halt  to return to the Boot Monitor.  Use the monitor command boot hd2 to
     boot the primary partition Minix has been installed in.  (If you need  to
     use  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  SCSI 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.

     The hard disk bootstrap is now showing the menu again, hit ESC once  more
     to  get  to  the  command prompt.  The command 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 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 IRQ 3):

          minix(=,Minix-vmd) {boot}
          dos(d,MS-DOS) {boot hd1}

     MS-DOS is assumed to be in the  first  partition  in  the  example  above
     (hd1).   When  finished  type menu to see if the menu looks right.  If so
     hit '=' to start Minix-vmd.

  Filling /usr
     Type these commands to fill /usr from the USR.TGZ floppy set:

          cd /usr
          vol [size] /dev/fd0 | gzcat | tar xvfp -

     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.

     If USR.TGZ is already present on the hard disk in  an  MS-DOS  partition,
     then this commands can be used to extract it to avoid the floppy detour:

          cd /usr
          mcopy hd1:USR.TGZ - | gzcat | tar xvfp -

     The file doesn't have to be in the root  directory  of  hd1,  of  course,
     hd6:/TMP/USR.TGZ  would  name a file on the first partition of the second
     hard disk in the directory \TMP.

     The /usr file system can also be filled through a network from  a  remote
     host  if  Minix-vmd  is  installed using the NETUSR floppy instead of the
     normal USR.  Follow the instructions in 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
     /usr/src/.rhosts, as root, and to use the following command on the remote

          rsh -l root minix-box 'cd /usr && gzcat | tar xvfp -' < USR.TGZ

     Two is to use ftp to copy the data directly from a Minix-vmd FTP site  by
     using these commands under Minix-vmd:

          cd /usr
          ftp -c ftp-site:dir/USR.TGZ | gzcat | tar xvfp -

     The sources may be installed using exactly the same  commands,  but  with
     USR.TGZ  replaced by SRC.TGZ.  Note that this means that the sources must
     also be extracted relative to /usr.

  Active on Boot
     You  may  want  to  make  the  Minix  partition  active  so  that  it  is
     automatically  booted.   With  DOS  fdisk or Minix 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 DOS at a keypress.
     You can even set timeouts.  To boot Minix automatically after 5 seconds:

          main() {trap 5000 minix; menu}

     See monitor(8) for all the details on the monitor.

     If you don't trust this then you can rig up a  diskette  that  boots  the
     Minix partition when left in the drive:

          installboot -m 2 /dev/fd0 /usr/mdec/masterboot

     The number 2 indicates the hard disk or partition that  must  be  booted,
     i.e.  /dev/hd2 in this example.

     A crash course on the Minix devices in /dev:   The  two  hard  disks  are
     named  hd0  and 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 hd1, hd2, hd3, and hd4.  And for disk 1
     they are named hd6, hd7, hd8, and hd9.  These partitions may contain file
     systems,  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 hd1 are named hd1a, hd1b, hd1c,  and  hd1d.   The  other
     partitions  may have four subpartitions that are named in the same way by
     adding a letter from a to d.  So one disk may have four  partitions,  and
     16  subpartitions  total.  SCSI disks are named in the same way, from sd0
     to sd39d for all possible devices for all eight SCSI  targets.   The  two
     floppy  disks are fd0 and fd1.  Each may have four partitions named fd0a,
     fd0b, ...  fd1d.  The command MAKEDEV knows  how  to  make  devices,  and
     DESCRIBE  can  tell  you  what an unknown device may be, or even what all
     devices in  /dev  may  be  if  called  without  arguments.   Devices  are
     described fully in dev(4), and in device specific manual pages like fd(4)
     and hd(4).

  MS-DOS virtual disks
     Minix-vmd has a special driver that allows one to use a very  large  file
     on  an  MS-DOS  FAT file system as a Minix-vmd disk, see dosd(4).  If you
     don't have a partition available  for  Minix-vmd  then  you  can  do  the

     Boot from ROOT and specify the name of the DOS file to use  in  the  boot
     environment, e.g.

          dosd0 = hd1:minix

     This is the file "minix" on what is likely to be your C:  drive.   Before
     running part use

          dd if=/dev/zero bs=1k count=80000 | mcopy - hd1:MINIX

     to make a large file (in this case 80000 kb.)  With  mdir  hd1:  you  can
     tell  if  you  have  done  it  right.   Now  you have a disk device dosd0
     available that you can partition and use.   There  are  no  subpartitions
     however, so you can only make a primary partition table.  (See dosd(4) on
     why you should start partitions on even-numbered sectors.)  You  can  use
     dosd1  for  the root file system, dosd2 for /tmp+swap, and dosd3 for /usr
     for instance.  To boot this system you need a version of the boot monitor
     that runs under MS-DOS.  This command will copy it to DOS:

          mcopy /usr/mdec/ hd1:BOOT.COM

     Under DOS the command boot minix will then boot Minix  from  the  virtual
     disk.  Don't forget to repeat the dosd0=hd1:minix setting.  Alas you need
     a spartan DOS configuration for the monitor to work, a 386  based  memory
     manager  doesn't  allow  a  jump to protected mode.  MS-DOS 6.0 and later
     have all kinds of tricks to change the way it is booted.

  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 vdisk.conf(5).

     To use a virtual disk first create the necessary  partitions  when  setup
     wants  you  to,  then use the s command to start a subshell (or log in on
     another virtual console as root.)  Edit the file /etc/vdisk.conf and  use
     the command

          vdisk_ctrl -c /etc/vdisk.conf

     to initialize the virtual disk.  Exit the  shell  with  CTRL-D.   Do  not
     change  any  partitions  anymore  with  part unless the virtual disk that
     depends on those partitions is disabled.

     The editors available are elvis (a vi clone), joe (a simple  editor  that
     can look like several editors, including emacs under the name jmacs), and
     the old Minix mined editor.  Of these editors only elvis can recover your
     file after a system crash.  Only mined is available at installation time.
     (All you need to know about mined right now is that CTRL-X gets  you  out
     of it.)

  Installing on a SCSI disk
     Using a disk other than a hd disk complicates things  a  bit.   The  Boot
     Monitor  uses  the  BIOS,  so it names all disks with hd names.  So it is
     boot hd1 to boot partition 1, and rootdev=sd2a to  tell  Minix  its  root
     partition.   If you have both a normal and a SCSI disk then the disks may
     be hd0 and hd5 to the Monitor, and hd0 and sd0 to Minix.

  National keyboards
     The  directory  /usr/lib/keymaps  contains  keymap  tables  for   several
     national keyboards.  If you have a German keyboard for instance, then

          keymap -l /usr/lib/keymaps/german.kbd

     will load the German key translation  table  into  the  keyboard  driver.
     Setup  will  do  this  for  you when you choose a keyboard type, and will
     create a symlink /etc/keymap on the new root file system that  points  to
     the chosen keyboard table so that it is loaded at boot.

     Please send corrections and new keymaps to the person named  below.   (Do
     not send a Dutch keymap, buy yourself a real keyboard instead.)

  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 /usr/lib/fonts to give the console a proper
     font.  To load the Latin-1 font:

          loadfont /usr/lib/fonts/iso1.fnt

     The default font can be set by symlinking or copying the chosen  font  to
     /etc/font.  It will then be automatically loaded at boot.

     Below are a few useful suggestions.  Some of the information  can  be  of
     use in other situations than described here.

  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.)

     The console implements  the  same  escape  sequences  as  the  X11  xterm
     program.   As  terminal type vs100 is used, one of the alternate names of
     xterm.  When necessary one can also use xterm, minix, vt100, or ansi.

     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.

  Low on memory
     The normal installation requires that you have enough memory for a  large
     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.

     Several problems must now be solved:  There is not enough  memory  for  a
     RAM  disk,  ROOT is too big to be combined with USR on a 1.2 Mb diskette,
     and ROOT does not have enough free space in its /tmp to use  it  directly
     as  the  root  file  system.   So instead of ROOT we use a smaller floppy
     image named TINYROOT.  You still need ROOT to boot the  system  and  load
     the  Minix-vmd  kernel, because TINYROOT doesn't contain a kernel to save
     the necessary space.  The recipe to install Minix-vmd is now:   Boot  the
     machine with ROOT, type ESC and enter the following commands:


     The Minix kernel is loaded and the Monitor asks that you insert the  root
     floppy.   Replace ROOT by TINYROOT (optionally combined with USR) and hit
     a key to continue.  You can now install the system normally  with  setup.
     When  done  type halt to return to the monitor.  Do not yet use a command
     like boot hd2a to try the new system, but replace TINYROOT  by  ROOT  and
     type exit to reboot.  Again hit ESC and type


     to boot the system on the hard disk.  Rootdev must be  set  to  the  root
     file  system  of  the newly installed Minix-vmd, for 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 TINYROOT doesn't have a
     kernel, no kernel is installed on the hard disk.  So  let's  repair  this
     omission.   Log  in  as  root  on the new system, mount ROOT and copy the
     kernel image to its proper place:

          mount /fd0
          cpdir -v /fd0/minix /minix

     Use /fd1 instead of /fd0 if the floppy happens to be in the second drive.

     The installation will take quite some  time,  because  the  floppy  drive
     keeps  whirring  to  load, and reload 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.

  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 USR image onto a diskette for drive 0.  The USR
     bootstrap has been rigged to boot the other drive.

  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

          installboot -m 5 /dev/hd0 /usr/mdec/masterboot

     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.

     If the day comes that you want to repair the master  bootstrap  then  you
     can  use fdisk /mbr under MS-DOS 6.0 or newer, or the installboot command
     shown above without the number 5 to make the master  bootstrap  boot  the
     active partition again as is normal.

  Boot scripts and such
     Inspect /etc/rc and other rc files to understand how the  system  starts.
     /usr/lib/crontab and /usr/etc/daily are also interesting reading.

  The X Window System
     The command

          vol [size] /dev/fd0 | pkgadd -x - XF86-3.1.1

     installs the X11 package.  Read startX(1) after installation to know more
     about X11 under Minix.

     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  bin!   Only  in
     exceptional  cases  do  you  want  to become root.  Being root is fun for
     wannabe hackers; administrators know better.

     To make life easier for bin, the  home  directory  of  root  is  also  in
     /usr/src,  unlike  most UNIX systems where root lives in /.  The programs
     su(1), install(1) and 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 any of the supplementary group ids  is  zero.)   Operators
     should  share  the  shadow  password  of  root  by having ##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.

     The home directory of bin contains one important Makefile.  You  can  use
     it  to recompile all the commands and libraries of the system.  Type make
     to see the usage message.  If you want to compile just one  command  then
     you can simply type make to do so.  To put it in its proper place you may
     have to type make install.  Most Makefiles simply throw the  result  into
     the  bin  or  sbin  directories by default, so be careful when you update
     something important, first make a copy.  To compile just one library file
     use  make  CC=acc  ARCH=i386  or  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.)

     The kernel is compiled using the build(8) command.   There  is  not  much
     left  that  can  be  user configured, the old <minix/config.h> is gone in
     favour of <minix/cfg_*> that contain no configurable  parameters.   About
     the  only  interesting  parameter  left  among the Minix include files is
     NR_PROCS in <minix/const.h>.  It defines the maximum number of  processes
     the  system  can  run  at  once.   FS  also  has  several  of  these NR_*
     parameters.  In time all of these will become  boot  variables,  or  even
     runtime  variables.   The  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  DMA_SECTORS parameter is important if you use the ESDI or
     BIOS disk driver.  Increasing DMA_SECTORS  may  improve  disk  throughput
     significantly,  at  the  cost of DMA_SECTORS kilobytes.  You can increase
     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.

     Additions to the system can be made in the  /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
     adduser  command.   Make  all  new  home  directories in /home.  You as a
     system administrator will want your login to be a member of the  operator
     group,  and you will want the same $PATH setting as bin has, with all the
     extra sbin directories  full  of  commands  for  the  administrator,  see
     /usr/src/.ashrc.   You  also want to have ##root in the password field of
     your password file entry, so edit /etc/passwd as root.

     The author of this text uses three group zero names:  root, bin and  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 bin and clutter up /usr/src with personal things, and you sure
     as hell don't want to be root longer than is absolutely necessary.

     The TZ variable in /etc/timeinfo tells the time zone offset from the wall
     clock  time  to  GMT.   You  have  to change it for your time zone.  (See

     Electronic mail is sent by the 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 /usr/lib/smail/config anyway.

     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 console(4) to know all the details of the screen and keyboard.

  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:

          First alert all users  and  then  all  processes  of  the  impending
          shutdown then halt or reboot the system in one of various ways.  See

     reboot / halt
          Alert all processes of the system shutdown then reboot or halt.

          Halts the system by running shutdown -h now.

     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 shutdown -R to reset the system.

     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".

     These are some of the differences with standard Minix, those marked  with
     (P)  are  by  Philip  Homburg (, those marked with (K) by
     Kees Bot (

          Virtual Memory and paging to disk  is  by  far  the  most  important
          addition.   There  is  no  longer  a need for 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 fork(2) is done by page sharing.

          Two new file system types with  long  file  names.   Fast  automated
          checking of file systems on bootup. (K)

          Asynchronous I/O, VGA and keyboard drivers to support X11.   Patches
          to XFree86 to make it run under Minix. (P)
          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)

          Undervalued slave work needed to make any system look like a system.

          Executable caching, inode caching, name-to-inode caching. (P)

     The most important difference between standard Minix and Minix-vmd is not
     an  actual difference, but a difference in philosophy.  Minix is a simple
     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.


     /usr/ast    Honorary home directory of Andrew S. Tanenbaum.   Doubles  as
                 the place where the default setup for a new user is found.

     monitor(8),  boot(8),  part(8),  mkfs(1),  mount(8),  fstab(5),  hier(7),
     console(4),   dev(4),  adduser(8),  build(8),  @build(8),  cc(1),  TZ(5),
     mtools(1), vdisk.conf(5), rhosts(5), smail(8), shutdown(8), intro(2).
     "Operating  Systems  -  Design  and  Implementation  2/e"  by  Andrew  S.
     Tanenbaum and Albert S. Woodhull.

     The  notation  <file.h>  refers  to  a  C  language   include   file   in

     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  /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
     or  DO NOT send bug reports to, he doesn't
     want to know.

  Known Bugs
     Bugs we know about, but haven't fixed yet:

     The mail command is only halfway there.

     Inetd offers no UDP services.  There is  no  way  yet  to  probe  for  an
     incoming UDP packet without actually reading it.

     Running 'make clean' for Smail and Perl doesn't clean all.

     Backwards compatibility for standard Minix network programs fails on  the
     uname()  library  call  that  cannot  find  the  node name of a Minix-vmd
     machine.  As a kludge to fix this type
               uname -n > /etc/hostname.file
     or change /usr/etc/rc to do this at boot time.

     Minix-vmd offers only Minix-vmd and not much else.  Other free  UNIX-like
     systems have all the good software to get real work done.

     Kees J. Bot (