path: root/Distrib/InstallNotes.mdwn

Items of interest during install not mentioned elsewhere include the following. Arranged in the same order as Neal Walfield's [install guide](http://web.walfield.org/papers/hurd-installation-guide/english/hurd-install-guide.html) - (link is currently broken - see below for current instructions).

**_Currently, [Debian's installation instructions](http://www.debian.org/ports/hurd/hurd-install) are the most up-to-date._**<br /> Note the mirrors mentioned on debian.org have no hurd iso's. The iso's can be found [Here](http://ftp.gnuab.org/pub/gnu.iso)

## <a name="Table_of_Contents"> Table of Contents </a>

%TOC%

## <a name="1_Overview_Where_we_are_going"> 1. Overview - Where we are going </a>

There are currently four methods to install GNU

1. Tarball - The current documentation, for the tarball method, are [Debian's installation instructions](http://www.debian.org/ports/hurd/hurd-install), based on the original guide by Neal Walfield. The GNU official [installation page](http://www.gnu.org/software/hurd/install.html) is the canonical reference. See [[Distrib/TarballNotesHome]] for more info.
2. [[Distrib/BochsEmulator]] is an x86 emulator similar to the propietary [[Distrib/VmWare]] (which is not supported). See the [[Distrib/BochsEmulator]] page for more info. The Bochs project hosts a preinstalled GNU image that is periodicaly updated. You can get the latest one [here](http://sourceforge.net/project/showfiles.php?group_id=12580).
3. [CD-ROM iso images](http://www.debian.org/ports/hurd/hurd-cd) CD-ROM installs are becoming more and more popular. The CDs are based on the most current tarball at release time. See [[Distrib/CDNotesHome]] for more info.
4. The [crosshurd](http://packages.debian.org/crosshurd/) Debian package, which can be used instead of a tarball to install the base system. This is the recommended way to proceed.

* References to a `cross-install` script can nowadays be completely ignored by anyone not a maintainer. It is only used when creating a new tarball.

## <a name="2_Real_Estate_or_Finding_A_Home"> 2. Real Estate or Finding A Home </a>

For those who do not happen to have an available partition or an extra hard drive, this can be the longest step. In this case, we will need to repartition the hard drive. One solution is to use GNU's partition editor, Parted. It features not only basic partition editing, but also partition resizing and moving functions. It can be found at <http://www.gnu.org/software/parted>. The manual is quite complete and includes several tutorials. Also there's a frontend called [nparted](http://packages.debian.org/unstable/utils/nparted.html) to simplify usage.

The Hurd can only support partition sizes of up to approximately one gigabyte; anything much larger than this will not work. This limitation is a design decision that was made several years ago in which the file system server maps the entire partition into virtual memory. As the amount of virtual memory available on an ia32 is only four gigabytes of which only two gigabytes are available to the application and, of that, a significant portion is reserved for the code, the stack and the heap, the final, maximum contiguous virtual memory area that is left is generally about one gigabyte. This limitation is scheduled to be remove. Several other items, however, currently have a slightly higher priority.

Having said that, a single one gigabyte partition is more than enough for a working system. Many, however, prefer at least two partitions: one for a root partition and another for a home partition. This latter scheme is highly advised for developers interested in debugging Hurd servers.

The Hurd supports several extensions to the ext2fs file system format. Foremost among these are passive translators and a fourth set of permission bits for unknown users. In order to take advantage of these features, however, the owner of the partition must be set to Hurd. `mke2fs`, unless specifically overridden on the command line, will set the owner to whatever system core it is running on. As the Hurd will diligently respect this setting, we must be careful to set this appropriately or the Hurd may fail in subtle ways. Be aware that even if a file system is owned by a particular system core, others may still use it; they just may not be able to use certain extensions.

To create a file system, we use `mke2fs` and pass it `-o hurd` to designate the Hurd as the owner of the new file system. For instance:

    mke2fs -o hurd /dev/DEVICE

**_Note:_** You may wish to add a `-b 4096` option to `mke2fs` (the default is chosen depending on the size of the partition, and the support for block size 1024 is buggy). The command to check the block size is `tune2fs -l /dev/hda9` under GNU/Linux.

## <a name="3_The_Boot_Loader_Getting_GRUB"> </a> 3. The Boot Loader - Getting GRUB

GRUB is the bootloader of the GNU system, and it's currently the only one that supports the multiboot standard, necessary to boot the Hurd.

A word about GRUB. Unlike traditional boot loaders on the x86, such as LILO, GRUB is very powerful. It has a command line interface, bootp, dummy terminal support and a plethora of other features. In addition, it can boot most any operating system. If you have ever booted an alpha or sparc, you will understand what GRUB can do. Therefore, do not be scared: GRUB is better. You will like it. You will not go back.

To find GRUB, visit <ftp://alpha.gnu.org/gnu/grub>. Here, there is a source tarball and a floppy image. If you choose to download the tarball, it is a normal configure, make and make install. Included is a wonderfully complete manual on how GRUB works. Read it. If, on the other hand, you choose to download the floppy image, it is sufficient to dump it to a floppy disk to get a working GRUB:

    dd if=grub-boot-VERSION.image of=/dev/fd0

You can always install GRUB onto your hard drive at a later date.

For instructions on using GRUB, see either the info documentation or the quick reference notes on this wiki:

* [[Distrib/GrubNotes]] - quick reference

## <a name="4_Cross_Install_Cross_Installing"> </a> 4. Cross Install - Cross Installing GNU

The recommended way to cross install the Hurd is by using the [crosshurd](http://packages.debian.org/crosshurd) Debian package. Unfortunately, it's broken right now (2003-10-10), so you'll have to use the old tarball method.

Download the base system `gnu.tar.gz` from <ftp://alpha.gnu.org/gnu/hurd/contrib/robertmh/> .

The tarball is setup to extract everything into the current directory. After mounting the partition and changing to the mount point, we just need to extract the archive. In the following example, we assume that the root partition is mounted on `/gnu`.

    cd /gnu
    tar --same-owner -xvzpf ~/gnu.tar.gz

**_NOTE:_** This should NOT be confused with the `cross-install` script method. It is only used by maintainers when creating a new tarball.

## <a name="5_Booting_GNU"> </a> 5. Booting GNU

Now things are setup to boot GNU for the first time. Verify that the GRUB boot disk is in the drive and reboot. If all goes well, a GRUB menu will be displayed. Hit c for the GRUB command line.

First, the root file system needs to be set. GRUB uses a partition nomenclature that is a bit different from either GNU or GNU/Linux: both IDE and SCSI drives are named `(hdN)`. `N` is the drive number (zero based) as reported by the BIOS. That is, GRUB makes no distinction between IDE and SCSI disks. The partitions, like the disks, are also indexed numerically from zero: `(hdN,M)`. If this sounds bad, relax: GRUB is also helpful.

To determine on which file system a particular file resides, one method is to use the find command. When issued this command, GRUB searches on each file system for the specified file and prints where is was found. Here we search for the kernel, `/boot/gnumach.gz`.

    grub> find /boot/gnumach.gz
     (hd0,0)

As we can see, GRUB is indicating that `/boot/gnumach.gz` is on `(hd0,0)`. Thus, we set the root respectively:

    grub> root (hd0,0)
     Filesystem type is ext2fs, partition type 0x83

Next, GNU Mach needs to be loaded. In addition to loading the binary, at least one option, the root partition, must be specified. This will be used by the Hurd itself. As such, it must be in terms that the Hurd can understand.

GNU Mach labels disks starting at zero. IDE drives are prefixed with hd, while SCSI disks are prefixed with sd. Like GNU/Linux, drives are number by their position on the controller. For instance, the primary master is `hd0` and the secondary slave is `hd3`. Partitions use the BSD slice naming convention, and append `sM` to the drive name to indicate a given partition. Note that `M` is a one, not zero, based index. The slice number is simple to calculate: just increment what you used for GRUB by one.

Since the Hurd has not yet been configured, it must be run in single user mode. Adding a `-s` to the kernel command line is all that is required.

Thus, continuing with the above example and assuming that the first drive in the master on the secondary controller, we would have:

    grub> kernel /boot/gnumach.gz root=device:hd2s1 -s
     [Multiboot-elf, ...]

NOTE: If after running this command you see GRUB Error 28, according to the [GRUB Troubleshooting](http://www.gnu.org/software/grub/manual/grub.html#Troubleshooting) documentation, you may need to tell grub that you have more memory by using the uppermem command. For example, if you have 256MB of RAM and running **displaymem** within GRUB shows that you have less memory than that, you can type **uppermem 262144** to tell GRUB about the additional memory.

Next, the root file system server and the exec server must be loaded. This is done using GRUB's boot module capability. The parameters are the semantics by which the kernel passes some important values to the servers.

    grub> module /hurd/ext2fs.static \
                 --multiboot-command-line=${kernel-command-line} \
                 --host-priv-port=${host-port} \
                 --device-master-port=${device-port} \
                 --exec-server-task=${exec-task} -T typed ${root} \
                   $(task-create) $(task-resume)

         [Multiboot-module  0x1c4000, 0x2cfe6a bytes]
    grub> module /lib/ld.so.1 /hurd/exec $(exec-task=task-create)
         [Multiboot-module  0x494000, 0x27afe bytes]

**_Important:_** each module string should be asingle separate line _or_ line wrapped with a backslash at the end of each line. Remember to make sure there are **_no trailing spaces!_** Adding this to GRUB's `menu.lst` file as soon as possible is advised.

Finally, GNU can be booted:

    grub> boot

Sit back and watch the messages. This is actually more important than one might think as there is a bug in GNU Mach whereby hitting a key during the boot process causes the kernel to panic.

If GNU fails to boot, it could be due to shared IRQs: GNU Mach does not play well with these. You can verify your situation by looking at, for instance, the `/proc/interrupts` file under GNU/Linux. Also, as GNU Mach does not support loadable kernel modules, many of the drivers are compiled into the default kernel. If you have old peripherals, this can be a significant problem: a device may respond badly to a probe intended for a different device. Building a new kernel with only the required devices drivers will usually solve this problem. GNU Mach is easily cross compiled. If you are running Debian, try the `gcc-i386-gnu` package.

If this does not help, explore the resources listed at the end of this document. Finally, ask on the appropriate mailing list.

There are some cavaets to the boot process:

* **IMPORTANT!** Remember when first booting into your freshly un-tarred distribution, you must pass the `-s` option to `/boot/gnumach.gz`. Failure to do so means that you won't get single-user mode.
* **IMPORTANT2!** Add the `--readonly` flag to the file system server in your GRUB `menu.lst` file. This is a work-around to get `fsck` working properly. Don't forget, everything must be on ONE line, or ended with a backslash!
* **IMPORTANT3!** If you have created the filesystem with a later version of e2fsprogs than the one installed in the tarball, it **might** happen that fsck fails and you can't boot multiuser. The workaround is to copy `/bin/true` into `/sbin/e2fsck` and `/sbin/fsck.ext2`, then boot multiuser and install the latest e2fsprogs.

    title GNU (kernel GNUmach 1.3)
    root (hdX,Y)
    kernel /boot/gnumach.gz root=device:hdXs(Y+1)
    module /hurd/ext2fs.static --readonly                  \
           --multiboot-command-line=${kernel-command-line} \
           --host-priv-port=${host-port}                   \
           --device-master-port=${device-port}             \
           --exec-server-task=${exec-task}                 \
           -T typed ${root} $(task-create) $(task-resume)
    module /lib/ld.so.1 /hurd/exec $(exec-task=task-create)

Where `hdX,Y` is the appropriate hard disk and partition number, in GRUB format. `hdXs(Y+1)` is the GNUmach format - because Mach partitions start at 1, unlike GRUB partitions that start on 0 (zero).

It is important that each module string is only a single separate line, or by escaping the EOL (end of line) with a back slash. Remember though to make sure there are **_no trailing spaces!_**

**_GRUB floppy and iso images:_** These are available from <http://www.copyleft.co.nz/links.html>. These have been built with the correct strings and only the root and boot partitions names need to be editied.

## <a name="6_Native_Install_Finishing_the_I"> 6. Native Install - Finishing the Installation </a>

Once a prompt comes up, and any time that the the Hurd is in single user mode, it is necessary to set the terminal type:

    export TERM=mach

(Repeat this each time you boot in single user mode)

Be warned that CONTROL-C and family will not work in single user mode.

We can now run the native-install script. This will configure the packages and set up several important translators:

    ./native-install

Right before the script terminates, it will indicate that it needs to be run a second time. Follow its instructions and reboot using the reboot command. Again, go into single user mode.

Now it is advisable to enable swap. The mach kernel dislikes running without swap and is unlikely to last through the installation, especially on systems with little physical RAM. Although you can enable swap later on after running `./native-install` for the second time, turning swap on early increases your probability of getting there.

This will start the default pager, create a device corresponding to the swap partition, and turn swap on on that partition:

    /hurd/mach-defpager
    cd /dev
    ./MAKEDEV hdXsY
    swapon /dev/hdXsY
    cd /

**IMPORTANT!** When enabling swap please be very sure that the partition really is swap. If you point `swapon` to a data partition it will use that for swap, overwriting any data you may have there.

Now run `./native-install` for the second time and go through a series of prompts.

Next, edit `/etc/fstab` to add the home partition and swap space. By default, `nano` is the only editor installed by the the base distribution (not `ae` nor `vi`). It is very important that swap space be used: the Hurd will be an order of magnitude more stable. Note that the Hurd can transparently share a swap partition with Linux, the kernel, but will happily page to any device including a raw partition such as your home partition.

Here is an example `/etc/fstab` file:

    # <file system>  <mount point>    <type>   <options>  <dump> <pass>
    /dev/hd2s1        /               ext2       rw         0      1
    /dev/hd2s2        /home           ext2       rw         0      2
    /dev/hd2s3        none            swap       sw         0      0

Remember to create any devices using the `MAKEDEV` command.

When you first boot, your `/home` directory will _not_ be auto-mounted. You must set a passive translator on that node to access that partition. The correct syntax for this is: <br />`settrans -p /home /hurd/ext2fs /dev/hd2s2`

To mount an nfs partition, use the nfs translator. When run as non-root, the translator will connect, for obvious reasons, to the nfs server on a port above 1024. For this to succeed under GNU/Linux, the insecure option must be added to the export line. Here is an example `/etc/exports` file:

    /home   192.168.1.2(rw,insecure)

To mount this from a GNU box:

    settrans -cgap /home /hurd/nfs 192.168.1.1:/home

## <a name="7_Configuration_Making_the_Syste"> 7. Configuration - Making the System Usable </a>

* After you install, you'll want to do several _important_ things:
  * Run `passwd` to give the root user a password. By default, root does not have one.
  * Run `adduser` to give yourself a user account. _Do not_ use root indiscriminately.
  * Run `MAKEDEV` to create devices in `/dev` for your hard disk and other required devices.
  * Since the Hurd does not use `ld.so.conf`, you will want to specify where the X Window System keeps its libraries. Do this by adding the following line to your `/etc/profile`: <br />`export LD_LIBRARY_PATH='/lib:/usr/X11R6/lib'`
  * run `/etc/cron.daily/find` to allow `locate` to function.

* [[GetNetworkRunning]]
  * Hopefully Mach will recognize your hardware. If it doesn't you have to recompile in most cases.
  * copy over your `/etc/resolv.conf` from GNU/Linux to allow your DNS to resolve correctly.

* Prepare system for new packages.
  * a recommended `/etc/apt/sources.list`: <br /><code>deb <http://ftp.gnuab.org/debian> unreleased main<br /> deb <ftp://ftp.debian.org/debian> unstable main <br /> deb-src <ftp://ftp.debian.org/debian> unstable main</code>
  * There are some extremely useful cross-platform 'apt' tricks that can be used to get packages when using Debian GNU/Linux (possibly others) for installation on GNU. This is especially useful if your GNUMach doesn't recognize your network card. The steps are covered in the file `/usr/share/doc/apt-doc/offline` which has been used by several Hurd developers successfully.
    * create an `/etc/apt/apt.conf.offline` like [[AptConfOffline]].
    * consider setting up a few [[CrossPlatformAliases]] for use under Debian GNU/Linux while the Debian GNU/Hurd partitions are mounted.
  * select the `apt` method from within dselect.

* [[Xfree86]]

* New packages - Hopefully you are able to get your network working but since the default GNUMach is only configured for a few ethernet cards you may need to recompile your GNUMach to get it working with your network hardward.
  * Install these extremely useful packages
    * `dialog` -- Debconf uses this for interactivity. You should install this first to allow you to configure other packages as they are installed.
  * It's a very good idea to bring your packages up to date by running: `apt-get update && apt-get dist-upgrade`
  * Some recommended packages
    * `screen` -- A terminal multiplexer is important because the Hurd does not yet have virtual consoles. Runs with GNU/Linux too.
    * `anacron` -- good to run cron jobs for a machine that is not on all the time.
    * `emacs21` -- a powerful editor.
    * `cvs` -- Concurrent Version System, you'll probably need this soon.
    * `bzip2, zip, unzip` -- compression tools.
    * `build-essential` -- preparing to build software.
    * `gnu-standards` -- GNU coding and package standards.

* Some packages use an erroneous dependency on `libc6-dev`. This is incorrect because libc6 is specific to GNU/Linux. The corresponding package for GNU is `libc0.3-dev`. If you find a package that is uninstallable due to a `libc6[-dev]` dependency, please send a bug report with a patch that fixes it. It is important that you don't hack your package system to workaround such problems, because that way you won't be able to spot them when they arrive. See the [[Distrib/PortingIssues]] for details about the problem and [[Distrib/BtsFiling]] for details on sending bug reports.
* Edit your `/etc/inetd.conf` and comment out all the services you don't need. Services that probably don't need to be running are `ftp`, `telnet`, `shell`, `login`, and `exec`.
* There appears to be a bug in `libnss-db` that causes networking to fail. To work around this edit `/etc/nsswitch.conf` and remove the `db` entries. (See <http://www.geocrawler.com/archives/3/333/2001/1/50/4907699/> )

## <a name="8_Final_Words_The_FAQ"> </a> 8. Final Words - The FAQ

* [[FrequentlyAskedQuestions]] - More than frequently asked questions

* [Hurd FAQ](http://web.walfield.org/papers/hurd-faq/)

* [[KnownHurdLimits]] - Limitations of the GNU operating system

## <a name="9_Works_Cited_Referenced_Materia"> 9. Works Cited - Referenced Materials </a>

On Sept 20, 2002 [[Main/DeepakGoel]] (a self-proclaimed newbie) posted a link to his personal [step-by-step installation](http://24.197.159.102/~deego/pub/hurd/install-guide/install.txt). The parent directory has additional material.

Tarball Notes: [[Distrib/TarballNotes20020816]] [[Distrib/TarballNotes20020523]]

CD-ROM Notes: [[Distrib/CDNotesJ2]]

Others who wish to post summaries of their installation experiences are encouraged to do so. The installer methods, package dependencies and file locations frequently do change without warning.

----

## <a name="Licensing"> Licensing </a>

 This work is based on the hard work by [countless Hurd users](http://web.walfield.org/papers/hurd-installation-guide/THANKS), documented and maintained by Neal H. Walfield. See the original for both reference and its licensing at <http://web.walfield.org/papers/hurd-installation-guide/>

The license for Neals work is under the [GNU GPL](http://web.walfield.org/papers/hurd-installation-guide/COPYING). However, in the Hurd Wiki license all content under the GNU FDL. (Unless the topic is mostly code or otherwise stated in the text.)

There are currently issues to be resolved around this matter, as far as I understand at least. Until an agreement can be reached this text, and the unclear status of this topic, will remain. The suggestion is to do something like this:

<dl>
  <dt><span style="background:"><font color="">Install Guide</font></span><a href="http://LOCATION/InstallGuide">?</a></dt>
  <dd> Neals Install Guide in its original form </dd>
  <dt><span style="background:"><font color="">Install Notes</font></span><a href="http://LOCATION/InstallNotes">?</a></dt>
  <dd> Or <span style="background:"><font color="">Install Guide Errata</font></span><a href="http://LOCATION/InstallGuideErrata">?</a> with all user input and additions </dd>
</dl>

There are several obvious issues with this as I can see

1. The [[InstallGuide]] must be kept editable by a select few people to avoid the current situation from repeating itself.
2. This loops back and kicks us in the butt because then we get:
  1. Synchronization problems with the original work
  2. Bottle necks: The people with edit access are too busy to synchronize with Neals guide
  3. Diverging guides
3. Annoyed users, we break the tradition of freely editable wiki content and we also have two guides saying different things.

-- [[Main/JoachimNilsson]] - 29 Dec 2002

## <a name="Blame_annotations"> Blame annotations </a>

 -- [[Main/SimonLaw]] - 29 May 2002 <br /> -- [[Main/GrantBow]] - 13 Oct 2002 <br /> -- [[Main/JoachimNilsson]] - 14 Nov 2002 <br /> -- [[Main/RobertMillan]] - 21 Nov 2002 <br />

First effort at straightening out the formatting mess ... added references to Neals' original, which this topic has become heavily based on.

-- [[Main/JoachimNilsson]] - 19 Dec 2002 <br />

Updated to the latest short-comings in the Hurd.

-- [[Main/OgnyanKulev]] - 11 Oct 2003

-- [[Main/TWikiGuest]] - 07 Dec 2003 (<r2q2@rocketmailNOSPAM.com>)

Updated iso information