-*- Text -*- Instructions for bootstrapping the Hurd from binary images (i386). Last updated 13 July 1996 This directory contains i386 binaries for the Hurd and various programs built to run under it. All program binaries are stripped to save disk space; the installed libraries have the debugging information stripped to speed linking. See the file SOURCES to see where each package came from. Remember that you must adhere to the GNU General Public License and the GNU Library General Public when distributing this binary snapshot. See /share/misc/COPYING and /share/misc/COPYING.LIB for copies of these licenses. If you have noticed that these steps are rather long and a bit too complex, you are right. But we didn't want to delay the release just in order to make the installation prettier. You can rest assured, however: Making it prettier and easier is one of our more important priorities. STEP I: Fetch the file `grub-boot.image' from the FTP site. It should be in the same directory as the Hurd binary image tar file. Copy this file onto a fresh floppy with the command: dd if=grub-boot.image of=/dev/fd0 bs=512 This is your `grub boot floppy', referred to below. Unpack the binary distribution onto a fresh disk partition, which needs to be BSD FFS format. The boot loader we use (GRUB) does not yet understand how to boot from a Linux ext2fs filesystem, though this is expected to change very soon. Ideally, you should make a new disk, labelling it with the BSD `disklabel' command. Make sure you leave cylinder 0 unused; the A partition should start at cylinder 1. Make the A partition large enough to hold the entire Hurd binary image, and then some, and make a B partition for swap. Use newfs to make a filesystem on the A partition, mount it, and extract the entire Hurd image into it. If you do not have a system running BSD, you can fetch the NetBSD install floppies and do this step using them. (You do not need to install NetBSD itself.) See the instruction subroutine labelled `Installing from NetBSD boot floppies' and follow them. We plan to have our own boot floppies soon, which will make this all a fair bit easier. STEP II: You might need to change the device on which paging is done. This is done in a file in the Hurd partition called `boot/servers.boot', on the line which looks like: /dev/sd0b $(add-paging-file) $(default-pager) `sd0b' is the paging device. Replace this with the correct device name (this is a mach partition name), or comment out the line if you don't want paging. Note that you don't have to do anything to initialize swap partitions, unlike Linux. STEP III: You can now boot the Hurd. Boot the grub boot floppy. When the menu comes up, select one of the single user boot commands, depending on whether you have a SCSI disk (sd0) or an IDE type disk (hd0). If you put the Hurd on something other than partition `a', then you will need to edit the boot commands appropriately before booting. (Editing the commands using grub only affects what you boot that time, it does not affect what the floppy does the next time you boot it.) Mach should load, and then the Hurd should start, saying something like: Hurd server bootstrap: ufs exec init proc auth. Single-user bootstrap: term sh. bash# STEP IV: When GNU boots the first time, you might see some confusing messages, and you may notice that pipes don't work. In order to set up the translators for this to be a fully functional Hurd system, say /bin/sh /SETUP This will set up some initial translators so that the system runs normally, and then offer to reboot the system. When it comes back up, boot it single-user again, so that you can do step V. NOTE: Do NOT RUN BSD FSCK on a Hurd FFS! (Hurd partitions, especially the root partition, may have filesystem extensions that BSD does not know about. Most of these are ignored by the BSD kernel and filesystem tools. One of them, `passive translators' (a/k/a non-transient mounts), is not understood by the BSD fsck. If you run the BSD fsck on a Hurd partition with such translators, things might fail *massively*. The Hurd version of fsck does not, of course, have any such problem. (The Hurd root partition needs to have such translators installed in order to work correctly. Other partitions don't; the filesystems support compat options to prevent the use of Hurd filesystem extensions.) STEP V: If you want to be able to boot this disk without using the floppy each time, then run the script /INSTALL-GRUB-MBR; give it the arg the name of your disk without any partition. Something like /INSTALL-GRUB-MBR sd0 is called for. The menu that grub provides is found in /boot/grub/menu.lst. You can edit that file to change what options the menu provides. (You can change the one on the floppy by mounting the filesystem it contains and editing the file there.) STEP VI: Now you have a Hurd system. But in order to make it fully usable, do the following: *** make devices cd to /dev and make devices. Say `MAKEDEV dev1 dev2 dev3 ...'. Supported devices are: o any hard disk device you have; you must specify both unit number *and* partition. Something like `sd0a' or `rd1f' is called for. o floppy disk drives, give something like `fd0' or `fd1'. For hardwired terminals, MAKEDEV doesn't know how to do it yet. To create /dev/tty00, where `tty00' is the Mach device name for the terminal, do settrans -c /dev/tty00 /hurd/term /dev/tty00 device tty00 *** setup network If you want to use the network, set it up thus: settrans /servers/socket/2 \ /hurd/pfinet --interface=eth0 --address=NN.NN.NN.NN \ --gateway=GG.GG.GG.GG --netmask=MM.MM.MM.MM where NN.NN.NN.NN is your IP address (not hostname, IP address). GG.GG.GG.GG is the address of an IP gateway, and MM.MM.MM.MM the netmask for the local subnet. If your host is isolated, then you can omit the gateway, and the netmask argument is optional if you don't use subnetting. Pfinet currently only supports a single active interface. Parameters may be changed while pfinet is running by using fsysopts, e.g.: fsysopts /servers/socket/2 --netmask=MM.MM.MM.MM Make sure you edit /etc/resolv.conf and/or /etc/hosts for the nameserver to work properly. *** mount partitions You can mount a partition (say hd0a) by saying: settrans /mnt /hurd/ufs /dev/rhd0a The name `/dev/rhd0a' must have been created using `./MAKEDEV hd0a'. (This is equivalent to Unixy `mount /dev/hd0a /mnt'.) (Note that you are using the *RAW* device here. In theory, it's irrelevant [and this is really only being used to get a name in a clever but strange way], but there are minor bugs in the non-raw versions, so don't try and use them.) If it's a Linux ext2 format disk, just do settrans /mnt /hurd/ext2fs /dev/rhd0a You can make it readonly thus: settrans /mnt /hurd/ufs -r /dev/rhd0a For more information on settrans, see the end of this file. *** mount nfs NFS mounts, not surprisingly, are done thus: settrans /mnt /hurd/nfs /remote/file/system remote.host.org (You may also use the host:fs and fs@host notations if you prefer.) NFS supports many options; use `/hurd/nfs --help' to see them all. *** edit configuration files Edit the password file (/etc/passwd) appropriately. Add any serial lines you have terminals on to /etc/ttys. Set your hostname with `echo foo.bar.baz > /etc/hostname'. This will then be permanent until you change the file. Edit /etc/fstab according to the disk mounts you've installed; this will control which partitions `df' prints and which partitions get `fsck' run for them at boot time. Edit /etc/hosts if you want to. Edit resolv.conf to provide for name service appropriate to your location. Once you've completed these steps, you can reboot the system multi user. Enjoy! MISCELLANEOUS NOTES: Fscking: /sbin/fsck is a wrapper that invokes filesystem-specific backend programs for each particular type of filesystem; these backends do the actual work (they can be found in the same directory, with names like /sbin/fsck.ufs and /sbin/fsck.ext2). /sbin/fsck will currently only work with filesystems that have entries in the file `/etc/fstab'; for those, it will try to be intelligent about making active filesystems readonly before fscking them, and telling them to incorporate any changes that result (the backend fsck programs do not know anything about active filesystems). However, it is up to the user to make sure that /etc/fstab accurately reflects reality. /etc/fstab is the same as in most unix systems -- any filesystems that are there and have a non-zero pass number will be automatically fscked during a multi-user boot. You'll certainly want to make an entry in /etc/fstab for the device that corresponds to your root filesystem (and make a device entry for it using MAKEDEV, as described above). GDB: The version of gdb included in this release has various features not used by most systems, in particular, the `thread' and `info thread' commands. The Hurd gdb can also debug running programs without halting them, which is useful to debug crucial system servers that can't be stopped without wedging the system. To do this, give the commands `set task pause off', `set exceptions off', and `set signals off', before attaching to the process. Of course, gdb may get confused because data structures are changing underneath it, but this generally works pretty well. The `portinfo' program is also very useful for debugging. SETTRANS: In all these cases, note that all the args after `/mnt' are a command line being sent to the filesystem program when it starts. The syntax of settrans is: settrans [settrans-option-args] file command-line settrans itself also supports several args. (Use settrans --help for a summary.) To see the args supported by a ufs or ext2fs, say `/hurd/ufs --help' or `/hurd/ext2fs --help'. Once a filesystem is running, some options may be changed at runtime using the `fsysopts FSYS' command, where FSYS is the mount point (note that there is currently no easy way of finding out which ones). The mounts created this way are not transient--they will last across reboots, being recorded directly on disk. To get rid of one, say: `settrans /mnt' with no further args. The command `showtrans /mnt' will show you where it's at right now. However, note that to have them automatically fscked, you'll have to make entries in /etc/fstab (see `fscking', above). You probably want to add all such mounts to fstab, so that the relevant disks are checked with fsck automatically on reboot, and so that programs like `df' know of them. A temporary mount (which lasts only until the filesystem program is killed or the system is rebooted) can be accomplished by giving the -a option to settrans thus: `settrans -a /mnt /hurd/ufs /dev/rsd0a'. (Note the placement of this option, as an arg to settrans, is different from the -r options you might give to the filesystem.) `showtrans' does not display these temporary mounts. CRASH SERVER: When programs get fatal signals in the Hurd, they call the "crash server". Right now, the crash server suspends the program, and the rest of its process group. At that point, if you resume the program, it will exit. But you can also attach a debugger to it, and all it's current dynamic state will still be there. If you would rather have crashing programs just exit, and not suspend, then disable the crash server by saying `settrans /servers/crash'. You can always reenable it later, if you like, by typing the command `settrans /servers/crash /hurd/crash'. Core dumps are not yet supported. Subroutine: Installing from NetBSD boot floppies If you do not have a system running BSD, the NetBSD 2-floppy install set contains enough tools to make a new filesystem using newfs and copy to it from nfs. You can fetch these floppies from ftp.netbsd.org in the directory /pub/NetBSD/arch/i386/floppies. The NetBSD install script will start automatically when you boot from the floppies, and we suggest you use it in order to partition and set up your disk. Here are detailed instructions for this step, assuming you are using NetBSD boot floppies, and you have the Hurd binary snapshot unpacked somewhere accessible via nfs. It is assumed here that your machine's network address is MY-ADDR and that the nfs server's address is SERVER-ADDR. The nfs mountpoint on the server is presumed to be SERVER-DIR. (MY-ADDR and SERVER-ADDR should be IP addresses in dot notation, not hostnames.) Your server and your new machine need to be on the same network. If you installing this way, you probably want to do STEP II first, because your nfs server probably has more convenient editors than the NetBSD boot floppies. The boot floppies have only ed. A. Fetch the netbsd boot floppies from ftp://ftp.netbsd.org/pub/NetBSD/arch/i386/floppies. Put the images onto floppy disks using the instructions found on the FTP site. B. Boot the `kernel' floppy, and switch to the `filesystem' floppy when instructed. C. Proceed through the NetBSD automated installation script. When you are asked if you want to view the boot messages again, say yes. Then answer the disk geometry questions correctly, copying from what was printed at boot time. D. Tell the script that you want to use cylinders, not sectors, in specifying sizes. E. VERY IMPORTANT: Make the size of your `NetBSD' portion one cylinder less than the total amount listed. If the script tells you that you have 3045 cylinders, then say you want the NetBSD portion to be 3044 cylinders long. F. VERY IMPORTANT: Tell the script that your `NetBSD' portion should start at cylinder 1. Not 0. 1. G. Then allocate however much disk you want to your root partition and to your swap partition. The root partition must be big enough to hold the entire Hurd binary snapshot; it is strongly recommended that you make it a fair bit bigger than that. It is quite satisfactory to use only one filesystem partition in the Hurd. H. If you specify partitions beyond the root partition and swap, the script will ask you for a `mount point'. Type anything you like, it won't matter. I. Affirm to the over-eagerly questioning script that you really do want to smash your disk. NetBSD will proceed to create filesystems on all the partitions you specified in I.G-H. J. When the script says "populating ..." hit ^C. You are now done with the script. K. cd to /mnt. For each mount point that was gratuitously created in step I.H, say `umount NAME'. Then say `rm -rf * .*'. Make sure you are really in /mnt. This will delete whatever NetBSD has put on your new partition. L. Initialize the network with `ifconfig DEV MY-ADDR'. DEV was printed by the kernel when it booted; type `more /kern/msgbuf' if you want to see those messages again. (Sometimes ifconfig says that something is "offline". Ignore it.) M. Mount the NFS server partition with the conveniente command `mount SERVER-ADDR:SERVER-DIR /mnt2'. N. Copy the Hurd onto your disk with the command (cd /mnt2; tar cf - .) | (cd mnt; tar xfpv -) O. If you haven't done STEP II yet, then do it now; otherwise go on to STEP III.