-*- Text -*- Instructions for bootstrapping the Hurd from binary images (i486). Last updated 8 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. For the GPL'd sources (most of them) you are not allowed to distribute this binary distribution to third parties without distributing the associated source. All these sources are found on prep.ai.mit.edu along with the Hurd binary distribution itself. STEP I: 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. Make the disk partition with newfs or mkfs on your favorite BSD system. Then unpack the binaries with tar onto that partition. [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.] STEP II: You probably 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; see step III below for a bit about partition naming), or comment out the line if you don't want paging. Fsck and unmount the new partition before using it, to make sure it's clean. STEP III: Install the grub bootloader. The instructions for installing grub are found in INSTALL-grub, which is a copy of the installation instructions at http://www.uruk.org/grub. We have included binaries for the various pieces of grub in /boot/grub on your Hurd partition. So you can follow the grub installation instructions without needing to build the actual grub pieces. You may want to switch to using grub entirely; it is able to most other kernels too. Full instructions are available on at http://www.uruk.org/grub, or in the grub source (which you should find wherever you picked up this binary release). STEP IV: Boot the system with grub. You should get a grub boot menu with two entries, `hurd' and `hurd-single'. Select hurd-single. 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 V: 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 VI. 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 VI: Now you have a Hurd system. But in order to make it fully usable, do the following: *** making devices cd to /dev give the command `./MAKEDEV ptyp ptyq'. Also add any disk device you have; you must specify both unit number *and* partition. Something like `sd0a' or `rd1f' is called for. *** 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 *** mounting 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' during step VI.A. (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. *** mounting 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, and 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. 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.