-*- Text -*-
Instructions for bootstrapping the Hurd from binary images (i486).
Last updated 8 July 1996

This directory contains i486 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 `XXX, 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 IV:

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

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

When GNU boots the first time, you might see some confusing messages,
and you may notice that pipes don't work.

Before you change anything, you may have to make the root filesystem
writable -- if the clean bit wasn't set, it will have been made
read-only automatically, printing obvious warning messages to that
effect.  Since things aren't set up enough at this point to fsck it,
just make it writable using the command

  fsysopts / --writable

In order to set up the translators for this to be a fully functional
Hurd system, say

  /bin/sh /SETUP

Now run `sync' and then `halt'.  Boot the system again (still
single-user), and it should come up more sanely.

(CAVEAT: 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 VII:

Now you have a Hurd system.  Some things you will want to do before
you get going are:

A: cd to /dev and make useful devices.  At least pty's thus:
   ./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.

B: If you want to use the network, set it up thus:
   
     settrans /servers/socket/2 NN.NN.NN.NN eth0 MM.MM.MM.MM

   where NN.NN.NN.NN is your IP address (not hostname, IP address).
   MM.MM.MM.MM is the address of an IP gateway.  If your host is
   isolated, then you can omit that arg.

C: You can mount a partition (say hd0a) by saying:

     settrans /mnt /hurd/ufs /dev/rhd0a

(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

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

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.

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.

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.

You should also examine the /etc/rc script we've written; it's pretty
specific to our use right now and you might want to make sure it makes
sense for you.  Perhaps you will want to edit the password file too.


MISCELLANEOUS NOTES:

Fscking:

XXX MILES -- Please insert arg summary here XXX


GDB:

XXX MILE -- Please verify

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.