

USAGE(8)                  Minix Programmer's Manual                   USAGE(8)


NAME
     usage - installing and using Minix

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

  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, ESDI, or SCSI 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.

  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 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 ESC to get to the Boot Monitor prompt, set  the
     appropriate  variables,  use  save  to  store  the  settings  and menu to
     continue where you left off.

     To install the system you need two diskettes: a  bootable  root  diskette
     and  a  diskette  full  of  binaries  to  use  as /usr.  Let's call these
     diskettes ROOT and USR.  These two diskettes may also be  combined  on  a
     single  high  density  diskette.   In  that case the USR part is on the c
     partition.

     Insert the ROOT 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 /usr.  Remove ROOT, insert USR
     and answer the question with fd0, the name of floppy disk 0, or fd0c  for
     a combined diskette.  Login as root.

  Automatic Installation
     Type 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 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.

     With the '+' and '-' keys you can select the disk device to  install  on,
     probably  /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".





                                                                             1



USAGE(8)                  Minix Programmer's Manual                   USAGE(8)


     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.

     After  making  /usr,  it  is  immediately  put  to  use  to  replace  the
     installation /usr file system so that you can remove the USR diskette and
     insert the ROOT diskette (unless they are one and the  same).   The  root
     file system is filled with the contents of the ROOT diskette and slightly
     patched up to work on the hard disk (/etc/fstab.)

     The last step is simple and boring.  You have  to  enter  all  the  other
     floppies in the proper order to fill /usr completely.

     You can now skip the next section, but it may be instructive to  read  it
     anyhow.

  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.

     Run 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  /usr
     partition.   The  assumption is that you will use the second partition on
     the first hard disk, /dev/hd2, and that hd2a, hd2b and 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  SCSI 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
     part(8),  hd(4),  and  sd(4).   Start 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 /dev/hd0.

     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.

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

     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.

     Use the rest of the partition for the /usr subpartition.




                                                                             2



USAGE(8)                  Minix Programmer's Manual                   USAGE(8)


     When you are done check  that  /dev/hd2a  is  active  (the  *  after  the
     partition number) so you can boot from it later.

     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.

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

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

          mkfs /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 /dev/hd2c
          umount /dev/fd0
          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.  Make a file system for
     the root of at least 720 kb (1024 kb for Minix-386), and fill it from the
     floppy:

          mkfs -i 512 /dev/hd2a 720
          mount /dev/fd0 /fd0
          mount /dev/hd2a /mnt
          cpdir -v /fd0 /mnt
          umount /dev/fd0

     Edit the file /mnt/etc/fstab to name the new  devices.   It  should  look
     like this:




                                                                             3



USAGE(8)                  Minix Programmer's Manual                   USAGE(8)


          root=/dev/hd2a
          tmp=/dev/hd2b
          usr=/dev/hd2c

     Unmount the new root:

          umount /dev/hd2a

     Make it bootable:

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

     The automatic script would now set the ramimagedev  boot  variable.   You
     can  do this now using the edparams command, or you can postpone it until
     the testing fase later.  The setting should be:

          ramimagedev=hd2a

     All that is left to do is to fill /usr.  Type these commands:

          cd /usr
          vol 720 /dev/fd0 | zcat | tar xvfp -

     And insert all the floppies one by one in the proper order.

  Testing
     By now a binary Minix system is present on your hard disk.  Time  to  see
     if  it works.  Leave the ROOT diskette in the drive and type 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 ESC to get to the command
     mode, followed by boot hd2 to boot the primary partition Minix  has  been
     installed in.  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.  You can type  '='
     to start Minix, but you probably want to change the boot parameters.  Hit
     ESC once more to get to the command prompt.  The command 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:

          minix(=,Minix) {boot}
          test(t,Test) {boot hd2b}
          dos(d,MS-DOS) {boot hd1}
          save

     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.

  Names
     A standalone machine will have to be given a name.  In /etc/hostname.file
     change 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:



                                                                             4



USAGE(8)                  Minix Programmer's Manual                   USAGE(8)


          M root
          cp /etc/hostname.file /root/etc
          U root

     M and U scripts are quite useful to quickly mount a device.

  Adding the Sources
     Type these commands to  add  the  /usr/include,  /usr/src,  and  /usr/man
     trees:

          cd /usr
          vol 720 /dev/fd0 | zcat | tar xvfp -

     And insert the source floppies one by one in the proper order.

  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 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:

          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 partition that must be  booted,  you
     can use the numbers 1 to 9 for hd1 to hd9.

  Devices
     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 partititions, and
     16 subpartititions 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.






                                                                             5



USAGE(8)                  Minix Programmer's Manual                   USAGE(8)


  Editors
     The editors available are elvis  (a  vi  clone),  elle  (a  simple  emacs
     clone),  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 ramimagedev=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

          loadkeys /usr/lib/keymaps/german.map

     will load the German key translation  table  into  the  keyboard  driver.
     Copy  the  map  to  /etc/keymap once Minix is installed on the hard disk,
     because having to type one of these

          loadkezs -usr-lib-kezmaps-german.map
          loqdkeys =usr=lib=key,qps=french.,qp

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

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

  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 rootdev to the same value as 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.

     The automatic installation script knows how to handle this new situation.
     If you install manually then you have to use

          cpdir -vx / /mnt

     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.



                                                                             6



USAGE(8)                  Minix Programmer's Manual                   USAGE(8)


  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 TINYROOT
     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 ROOT to install the root file  system.
     Keep booting your machine with TINYROOT until you have recompiled a small
     kernel for your system.  Use the rootdev boot variable to select the hard
     disk root file system.

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

  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

          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.

  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 ramsize boot
     variable.  Add a few commands to /etc/rc to copy bits from  /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 NR_BUFS definitions in <minix/config.h>.  One megabyte
     is enough to keep all compiler passes in memory.

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  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, some programs  like  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 ones group
     id is zero.)

     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


                                                                             7



USAGE(8)                  Minix Programmer's Manual                   USAGE(8)


     have to type make install.  Read the Makefiles in the  commands  and  lib
     subdirectories  to understand how everything is put together.  If you are
     tight on memory then make may fail to traverse down the source  tree  and
     also  compile  things.   You will have to type make in each subdirectory.
     You can run make in /usr/src at the end to see if you've missed something
     or not.

     The login shell of bin is ash, the BSD shell.  It has  been  modified  to
     offer  simple  line editing using the editline(3) library.  Ash is rather
     big, so you may have to change bin's shell back to /bin/sh  with  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.

     The kernel is not compiled from the  master  Makefile.   To  make  a  new
     kernel you have to step into the tools directory.  There you can run four
     different make commands:

     make This makes all the different kernel parts and combines them  in  the
          file named image.

     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.

     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.

     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 image to the file /minix on the root file system.

     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  /usr/include/minix/config you can find a
     number of ENABLE_XXX variables that can be set to 0 to exclude, or  1  to
     include a particular driver.

     New 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  simply  by
     adding a password file entry, copying the contents of /usr/ast to the new
     home directory and to chown -R user:group it to the new owner.

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

     The function keys produce debug dumps, showing various  interesting  data
     about the system:





                                                                             8



USAGE(8)                  Minix Programmer's Manual                   USAGE(8)


     F1 - Process table
          F1 produces a process table dump showing process-id's, memory sizes,
          and who is waiting for what other process.

     F2 - Memory map
          Like F1.

     F3 - Console scrolling
          Select between hardware or software scrolling on the console.

     F5 - Ethernet stats
          Shows number of packets send or received and other interesting  data
          about the ethernet adapter.

     CTRL-F7 - Quit
          Sends a quit signal to all processes connected to the console.

     CTRL-F8 - Interrupt
          Sends an interrupt signal.

     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-\ to send interrupt and quit signals.

FILES

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

SEE ALSO
     monitor(8), boot(8), part(8), mkfs(1), mount(8), M(8), fstab(5), hier(7),
     TZ(5), mkdist(8).
     "Operating Systems - Design and Implementation" by Andrew S. Tanenbaum.

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 tar or 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.

     The ps command doesn't show any process names and arguments and  is  thus
     currently useless.

     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.

AUTHOR
     Kees J. Bot (kjb@cs.vu.nl)





                                                                             9

