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. Other 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 1540.) Minix for the 386 (Minix-386 for short) 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 one 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. These diskettes are named 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 the RAM disk 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 setup 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 the author's 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". Do not make the partition smaller than 20 Mb, and do not make it larger than 128 Mb (Minix-86) or 1 Gb (Minix-386). The system needs 30 Mb in compiled state.

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 disk driver, and the new Minix partition is carved up into two partitions, a 1440 kb root 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.)

To compute the size of the so-called "second level block cache" you are asked to specify the memory size of your machine. If you have plenty, i.e 4 Mb or more then simply hit RETURN.

You can now skip the next section and move to "Testing", but it may be instructive to read it anyway.

  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 to 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 a /usr partition. The assumption is that you will use the second partition on the first hard disk, /dev/hd2, and that hd2a is the root subpartition and hd2c is /usr. If you want to use the first partition on the second hard disk for instance, then substitute hd6 and hd6[ac] 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 are advised to use 1440 kb exactly. You can make it larger if you want to, but it is advisable never to 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 second subpartition is either empty or a "scratch" partition. Minix no longer uses the b subpartition for anything useful anymore, but it has become customary to have root on a and /usr on c. (You are free to ignore this convention, of course.)

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

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 the disk if that helps. Subpartition tables, other than 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

will put it there for sure.

You will start by making a file system for /usr and filling it partially. This may seem to be out of order, but you can't insert the ROOT floppy right now.

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:

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 with at least 512 inodes (files), and fill it from the floppy:

Edit the file /mnt/etc/fstab to name the new devices. In our example it should look like this:

Unmount the new root:

Make it bootable:

The automatic script would now set the rootdev and ramimagedev boot variables. You can do this now using the edparams command, but it is easier to postpone it until the testing phase. The settings should be:

  Testing
By now a new Minix system is present on your hard disk. Time to see if it works. Leave the ROOT diskette in the drive and type halt. You are now going to use the power of the Boot Monitor on the diskette to boot the Minix partition on the hard disk. Use the monitor command boot hd2 to boot the primary partition Minix has been installed in. (It is "hd2" in our example.) 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:

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.

  Adding the rest of /usr or the Sources
Run the setup command again. It will note that you have put a small Minix system on disk and offer to install a floppy set, like USR.TAZ (rest of /usr), SYS.TAZ (system sources), or CMD.TAZ (commands sources.) Setup will ask for the size of data on the floppies, which is by default simply the entire floppy. You need the USR.TAZ set if you want a working Minix system, SYS.TAZ if you want recompile the system or study it, and CMD.TAZ if you also want the sources of the simple commands. On a disk space starved machine you could opt to do without the commands sources, as they are not absolutely necessary to understand Minix.

Just in case you want to know, this is the command used by setup to install a floppy set:

  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.

  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:

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:

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 partitions, 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. Devices are described fully in dev(4), and in the device specific manual pages like fd(4) and hd(4).

  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

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 a key sequence like one of these:

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 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. (Unless you have an old mono adapter, because virtual consoles sit in video memory, and a mono adapter only has memory for one.)

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

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

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.

  Low on memory and only one 720 kb floppy drive
If you only have one 720 kb floppy drive and your system is low on memory then you can use the TINYROOT boot image. This image contains a small kernel with only the BIOS disk driver, 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 compiled a small kernel for your system. Use the rootdev boot variable to select the hard disk root file system. Do not use TINYROOT for anything other than booting, always use ROOT when mentioned.

  Floppy drive 1 is a high density 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

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 making Minix run out of 3 Mb memory. Memory you can spare can be used for a "second level block cache" on the RAM disk. The File System uses the second level cache to store copies of disk blocks that are pushed out of the normal (primary) block cache. The size of the primary cache is compiled into the FS server, but the size of the second level cache can be set with the ramsize boot variable. For Minix running in 286 mode you can set ramsize between 0 and 512. 512 kilobytes is enough to keep most of the compiler cached. Minix-386 can have a second level cache of up to 1024 kilobytes. The second level cache is a poor solution for Minix-386 however. The first thing to do when you set out to compile a new kernel yourself is to make a big primary block cache by enlarging the appropriate NR_BUFS and NR_BUF_HASH constants in <minix/config.h>. Disable the second level cache and set ramsize to 0. Alas the 286 can only address 64 kb at a time, so you can't enlarge its primary block cache.

  Lots of disk space
The maximum file system size is 1 Gb for Minix-386 and 128 Mb for Minix-86. (Minix-86 can handle larger file systems, but fsck can't check them.) Note that a Minix file system can only contain 65535 inodes (files), so the average file should be 16 kb to completely fill it. It may be better to make two smaller file systems. Besides, fsck takes ages on a large file system.

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 one's group id 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 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 hdboot
    First makes the image file and then copies it into the directory /minix. If there are already two images in that directory then the newest image will be removed to make space for this newer image. It is assumed that the oldest image is the most stable system image, one that always works, and that the newest image is experimental. Check beforehand what /minix contains before you run make hdboot. Remove the oldest image if you want another image to become the stable image. The Boot Monitor chooses the newest image in /minix to boot. You can use the monitor command ls minix to view the images present, and set the image variable to the full name of the image you want to use instead if the newest doesn't work. The images in /minix are named using the Minix release and version numbers with an extra revision number added to distinguish the images.

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 <minix/config.h> you can find a number of ENABLE_XXX variables that can be set to 0 to exclude, or 1 to include a particular driver. Another driver related variable is DMA_SECTORS. This variable sets the size of a buffer used by DMA based disk drivers (all but the floppy, AT, and Adaptec drivers). Raise its value to greatly improve throughput, especially writing. A value of 16 shows good results. (The BIOS driver benefits most, because it is a long way to the BIOS from protected mode, especially from 286 protected mode.) You can increase NR_CONS 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 4 consoles, EGA and VGA can have 8 consoles. The NR_PTYS variable sets the number of pseudo-ttys. You need pseudo-ttys to be able to login remotely over a network with the rlogin command. Each remote login session needs one pseudo-tty. If you fear that the system will now run out of processes then increase NR_PROCS. Configuring a new kernel is sometimes not enough to enable new devices, you sometimes need to use the MAKEDEV command to make new device files in /dev. For pseudo-ttys you also have to check if /etc/ttytab mentiones the new devices.

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 with the adduser command.

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. F1 lists processes and F5 shows ethernet stats, which may be of use now. 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:

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 shutdown(8).

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

CTRL-ALT-DEL
    Halt 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.

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), console(4), dev(4), adduser(8), TZ(5), mkdist(8), shutdown(8).
"Operating Systems - Design and Implementation" by Andrew S. Tanenbaum.

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

Some of the commands have changed since earlier Minix versions. For instance mkfs doesn't need a size argument anymore, and vol automagically determines if it needs to read or write. Keep this in mind if you use an older Minix version to examine the newer system.

BUGS
There are many PS/2 models, all different. Some will run Minix, some won't, some crippled if you lie to Minix by setting processor to 86. Almost no PS/2 has a standard disk, so setting hd to esdi or bios will be necessary.

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

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