#use wml::debian::template title="Debian GNU/Hurd — Configuration" NOHEADER="yes"
#include "$(ENGLISHDIR)/ports/hurd/menu.inc"

<h1>Debian GNU/Hurd Configuration</h1>

<p>
This document aims to provide an easy and relatively painless set of
instructions on how to configure Debian GNU/Hurd with a minimum
amount of effort.
</p>

<p>
It is based in Neal H. Walfield's <q>The Hurd Installation Guide</q>.
Many thanks to Neal for his contribution.
</p>

<h2>Overview </h2>

<p>
GNU is similar in nature to any Unix-like system: after logging in, the user is
presented with a shell and the familiar Unix VFS (virtual filesystem). Although
GNU tries to be POSIX compliant, it is <q>Not Unix</q>. GNU/Hurd builds upon many of
the Unix concepts and extends them to either add new functionality or to fix
what has been perceived as flaws in the original design. The most noticeable
difference is translators, user space programs which interact with the VFS.
These filesystems do not live in the kernel nor do they need to be run
as root; they only need access to the backing store and the
<code>mount point</code>. Another difference is that processes, rather than having a single
user identity fixed at creation time, have identity tokens which are disjoint
from the process, i.e. they may be added with the appropriate permission from
an authority or destroyed.
</p>

<p>
Being familiar with the Unix environment (and especially GNU userland, found in
popular variants such as GNU/Linux) is an imperative for feeling at ease in
GNU. Having experience with the Debian tools will also prove invaluable to the
configuration and maintenance of a GNU/Hurd box.
</p>

<p>
This guide endeavors to make installing GNU/Hurd as painless a process as
possible. If there are errors, they are most certainly the author's. Please
report them, along with any other suggestions or criticisms, to him; all are
gladly accepted.
</p>

#<h2> 2. Real Estate or Finding A Home </h2>
#
#<p>
#If you do not have an available partition or an extra hard drive, this can be
#the longest step. In this case, you will need to repartition the hard drive.
#One solution is to use GNU's partition editor,
#<a href="https://packages.debian.org/parted">Parted</a>. It features not only
#basic partition editing but also partition resizing and moving functionality.
#The manual is quite complete and includes several tutorials. Note that also
#there is a <code>63 GNU HURD or SysV</code> partition type, it should not be
#used or else the installation CD will not find it. Just use <code>83
#Linux</code>
#</p>
#
#<p>
#The Hurd supports several extensions to the ext2fs filesystem format. Foremost
#among these are passive translators and a fourth set of permission bits for
#unknown users (users without an identity, not the other user). To use these
#extensions, the owner of the partition must be set to <code>hurd</code>.
#<code>mke2fs</code>, unless specifically overridden on the command line, will
#set the owner to whatever kernel it is running on. As the Hurd will diligently
#respect this setting, care must be taken to set this appropriately or the Hurd
#will fail in subtle ways. Be aware that even if a file system is owned by a
#particular kernel, others may still use it; they just may not be able to use
#certain extensions.
#</p>
#
#<p>
#To create a filesystem, use <code>mke2fs</code> and pass it <q><var>-b 4096
#-I 128 -o hurd</var></q> to designate the Hurd as the owner of the new file
#system. For instance, assuming the partition is <tt><q>/dev/hda1</q></tt>:
#</p>
#
#<table><tr><td>&nbsp;</td><td class=example><pre>
# \# mke2fs -b 4096 -I 128 -o hurd /dev/hda1
#</pre></td></tr></table>
#
#
#<h2> 3. The Boot Loader </h2>
#
#<p>
#The bootloader of the GNU system is Grub, the GRand Unified Boot loader,
#and it is its main purpose to boot the GNU system core (Mach and the Hurd).
#Any boot loader that supports the multiboot standard, though, may be used to
#load Mach and the Hurd. At the moment (that we're aware of), GNU Grub is the
#only bootloader that supports such standard.
#</p>
#
#<p>
#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 almost any
#kernel. 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.
#</p>
#
#<p>
#It is probably better if you install
#<a href="https://packages.debian.org/grub2">Grub</a> before installing the
#Hurd, but you can always install it onto your hard drive at a later date.
#</p>
#
#
#<h2> 4. Cross Install </h2>
#
#<p>
#The next step is to get a base system. There are several alternatives, if you
#are running a Debian system you can use the package crosshurd. Otherwise you
#can get an updated base system tarball from any of the mirrors listed at
#<url "https://wiki.debian.org/DebianPorts/Mirrors" />.
#</p>
#
#<p>
#The tarball is set up to extract everything into the current directory.
#After the filesystem is mounted, the archive can be extracted.
#Assuming that the filesystem is on <tt><q>/dev/hda2</q></tt>, the mount point
#is <tt><q>/gnu</q></tt> and archive is in current user's home directory, the
#following is required:
#</p>
#
#<table><tr><td>&nbsp;</td><td class=example><pre>
# \# mount -t ext2 /dev/hda2 /gnu
# \# cd /gnu
# \# tar --same-owner -xvjpf ~/gnu.tar.bz2
#</pre></td></tr></table>
#
#
#<h2> 5. Booting GNU/Hurd </h2>
#
#<p>
#All is now in readiness to boot GNU/Hurd for the first time. Note that depending
#on your version of GRUB, small details with vary. Please make sure whether you
#have GRUB1 (aka legacy aka 0.95 and later up to 0.97), or GRUB2 (aka 1.95 and
#later). Examples below will provide both versions, make sure to pick the right
#one.
#</p>
#
#<p>
#Please also note that some problems have been reported when booting with only
#128MB memory, because of swap not being setup yet at this stage. Make sure to
#provide at least 256MB memory.
#</p>
#
#<p>
#If your system already has GRUB installed, just reboot it. Else, you need to use
#a Grub boot disk. On Debian, the grub-disk (grub1) or grub-rescue-pc (grub2)
#packages provides CD and Floppy disk images. Make sure that the Grub boot disk
#is in the drive, reboot. If all goes well, either a Grub menu or command line
#will be displayed. If the menu has a <tt><q>GNU/Hurd</q></tt> entry, you will
#probably be able to just reuse it to save a lot of typing burden. For now, if
#presented with a menu, press <kbd>c</kbd> to go to the command line.
#</p>
#
#<p>
#First, GNU Mach needs to be loaded. This requires knowing the filesystem
#and the path to GNU Mach. Grub uses a partition nomenclature that is a bit
#different from both Linux and the Hurd: both IDE and SCSI drives are named
#<tt><q>(hdN,M)</q></tt>. <code>N</code> is the drive number (zero based) as
#enumerated by the BIOS. That is, Grub makes no distinction between IDE and SCSI
#disks. <code>M</code> identifies the partition on the drive. It is zero based
#in grub1 but one based in grub2. If this sounds confusing, relax:  Grub is also
#helpful.
#</p>
#
#<p>
#To determine on which filesystem a particular file resides, Grub provides the
#<code>find</code> command. When this command is issued along with a filename,
#Grub searches on each filesystem for the specified file and prints where it was
#found. For example, to search for the kernel, <tt><q>/boot/gnumach.gz</q></tt>:
#</p>
#
#<table>
#<tr><td>&nbsp;</td><td class=example><pre>
#   grub1&#62; find /boot/gnumach.gz
#   (hd0,0)
#</pre></td></tr>
#<tr><td>&nbsp;</td><td class=example><pre>
#   grub2&#62; search -f /boot/gnumach.gz
#   (hd0,1)
#</pre></td></tr>
#</table>
#
#<p>
#Here, Grub1 indicates that <tt><q>/boot/gnumach.gz</q></tt> is on
#<tt><q>(hd0,0)</q></tt> and Grub2, on <tt><q>(hd0,1)</q></tt> (remember the difference
#in partition numbering between Grub1 and Grub2).  To save you a couple of
#typing, set Grub's root to that value:
#</p>
#
#<table>
#<tr><td>&nbsp;</td><td class=example><pre>
#   grub1&#62; root (hd0,0)
#</pre></td></tr>
#<tr><td>&nbsp;</td><td class=example><pre>
#   grub2&#62; set root=(hd0,1)
#</pre></td></tr>
#</table>
#
#<p>
#Before loading the kernel, at least one option, the root partition, must be
#specified on the command line. This will be used by the Hurd itself (i.e. not
#Grub). As such, it must be in terms that the Hurd can understand.
#</p>
#
#<p>
#GNU Mach enumerates disks starting at zero. IDE drives are prefixed with
#<code>hd</code>, while SCSI disks are prefixed with <code>sd</code>. Like
#Linux, drives are number by their position on the controller. For instance, the
#primary master is <code>hd0</code> and the secondary slave is <code>hd3</code>.
#Partitions use the BSD slice naming convention and append <code>sM</code> to the
#drive name to indicate a given partition. Note that <code>M</code> is a one, not
#zero, based index. The slice number is simple to calculate: if you have Grub2,
#just reuse the same index, if you have Grub1, just increment what was used for
#Grub1 by one.
#</p>
#
#<p>
#Since the Hurd has not yet been configured, it must be started in single user
#mode. Adding a <q><var>-s</var></q> to the kernel command line is all that is
#required.
#</p>
#
#<p>
#To sum it up, assuming that the first drive (i.e. <tt><q>(hd0)</q></tt>) is the
#master on the master controller, we would have:
#</p>
#
#<table>
#<tr><td>&nbsp;</td><td class=example><pre>
#   grub1&#62; kernel /boot/gnumach.gz root=device:hd0s1 -s
#   [Multiboot-elf, ...]
#</pre></td></tr>
#<tr><td>&nbsp;</td><td class=example><pre>
#   grub2&#62; multiboot /boot/gnumach.gz root=device:hd0s1 -s
#</pre></td></tr>
#</table>
#
#<p>
#Next, the root filesystem server and the <code>exec</code> server must be
#loaded. This is done using Grub's boot module capability. The ${var} are
#filled in by GNU Mach. The arguments are used by the Hurd to indicate what
#type of information is being provided. Since the ext2fs command line is very
#long, it can be broken up by escaping the newline character in the normal Unix
#fashion. Be sure that there is not space after the antislash at the end of each
#line. Also be sure to differentiate <kbd>{</kbd> and <kbd>}</kbd> from <kbd>
#(</kbd> and <kbd>)</kbd>. Mind the subttle differences between Grub1 and
#Grub2: Grub2 needs that the filename be repeated and quotes need
#to be used. Note that at this stage the <var>--readonly</var> option of
#<code>ext2fs.static</code> must not be passed.
#</p>
#
#<table>
#<tr><td>&nbsp;</td><td class=example><pre>
#  grub1&#62; 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]
#  grub1&#62; module /lib/ld.so.1 /hurd/exec $(exec-task=task-create)
#    [Multiboot-module  0x494000, 0x27afe bytes]
#</pre></td></tr>
#<tr><td>&nbsp;</td><td class=example><pre>
#  grub2&#62; module /hurd/ext2fs.static ext2fs \
#   --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)'
#  grub2&#62; module /lib/ld.so.1 exec /hurd/exec '$(exec-task=task-create)'
#</pre></td></tr>
#</table>
#
#<p>
#Alternatively, you can throw these lines into a <tt><q>menu.lst</q></tt>
#(Grub1) or <tt><q>grub.cfg</q></tt> (Grub2) configuration file in the partition,
#and load it by using <tt><q>configfile /path/to/menu.lst</q></tt> (Grub1) or
#<tt><q>configfile /path/to/grub.cfg</q></tt> (Grub2) from the grub prompt. You
#can of course also simply install grub in some MBR and point it to there.
#</p>
#
#<p>
#GNU/Hurd can be now booted:
#</p>
#
#<table><tr><td>&nbsp;</td><td class=example><pre>
#grub&#62; boot
#</pre></td></tr></table>
#
#<p>
#If GNU/Hurd 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 <tt><q>/proc/interrupts</q></tt> 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 there are old peripherals, this can be a problem: a
#device may incorrectly respond to a probe intended for a completely unrelated
#device and thereby cause a crash. Building a new kernel with only the required
#device drivers will usually solve this problem. GNU Mach is easily cross
#compiled. If you are running Debian, install the <tt><q>mig</q></tt> package,
#and your stock <tt><q>gcc</q></tt> should do.
#</p>
#
#<p>
#If this does not help, ask on the appropriate mailing list.
#</p>
#
#
#<h2> 6. Native Install </h2>
#
#<p>
#Once you are presented with a shell prompt, and any time that the Hurd is in
#single user mode, it is necessary to set the terminal type:
#</p>
#
#<table><tr><td>&nbsp;</td><td class=example><pre>
# \# export TERM=mach
#</pre></td></tr></table>
#
#<p>
#Be warned that <kbd>CONTROL-C</kbd> and family will not work in single user
#mode.
#</p>
#
#<p>
#We can now run the <code>native-install</code> script. This will configure the
#packages and set up several important translators:
#</p>
#
#<table><tr><td>&nbsp;</td><td class=example><pre>
# \# ./native-install
#</pre></td></tr></table>
#
#<p>
#Before the script terminates, it will indicate that you can now reboot and enter
#multi-user mode. Do so, this is the Hurd, welcome!
#</p>


<h2> Installation </h2>

<p>
You can simply use the Debian installer, see the
<a href="hurd-cd">prepared CD images</a>.
Then the following steps will be needed for proper configuration.
</p>

<p>
You can also get a pre-installed image and run it in qemu:
</p>

<table><tr><td>&nbsp;</td><td class=example><pre>
$ wget https://cdimage.debian.org/cdimage/ports/stable/hurd-i386/debian-hurd.img.tar.gz
$ tar xzf debian-hurd.img.tar.gz
$ kvm -m 1G -drive file=$(echo debian-hurd*.img),cache=writeback
</pre></td></tr></table>

<p>
To enable accessing the box through ssh, you can append
</p>

<table><tr><td>&nbsp;</td><td class=example><pre>
-net nic -net user,hostfwd=tcp:127.0.0.1:2222-:22
</pre></td></tr></table>

<p>
and ssh to your local TCP port 2222.
</p>

<p>
You can also convert the image to the VDI format for virtualbox:
</p>

<table><tr><td>&nbsp;</td><td class=example><pre>
$ VBoxManage convertfromraw debian-hurd-*.img debian-hurd.vdi --format vdi
</pre></td></tr></table>

<h2> Configuration </h2>

<h3> The Network </h3>

<p>
The Debian way is supported starting from sysvinit 2.88dsf-48 and hurd 1:0.5.git20140320-1: <tt>/etc/network/interfaces</tt> is used like on
Linux. The only difference is that network boards appear in <tt>/dev</tt>, and
interfaces should thus be specified as <tt>/dev/eth0</tt> etc.
</p>

#<p>
#First, make sure that your network card is recognized by GNU Mach:
#</p>
#
#<table><tr><td>&nbsp;</td><td class=example><pre>
# \# devprobe eth0
# eth0
#</pre></td></tr></table>
#
#<p>
#If <code>devprobe eth0</code> does not return <code>eth0</code>, the kernel
#didn't detect your network board and you need to try another board. For
#instance, qemu's e1000 board is not supported, the rtl8139 one should work:
#<code>-net nic,model=rtl8139 -net user</code>
#</p>

#<p>
#Starting from version 20120520-1, the hurd package includes DDE drivers which
#are used to support more recent devices (drivers are taken from Linux
#2.6.32). Translators for that are already set up for you, and all you
#need to do is to replace <code>eth0</code> (the mach driver name) with
#<code>/dev/eth0</code> (the DDE driver path) in the remainder of this document.
#</p>
#
#<p>
#It is possible to try to use the DDE driver even if GNU Mach has a driver:
#passing <code>nonetdev</code> on the gnumach command line will disable the GNU
#Mach driver, and the DDE driver will start working.
#</p>

<p>
If network does not seem to work, use the following to get debugging information
from the DDE driver:
</p>

<table><tr><td>&nbsp;</td><td class=example><pre>
 \# settrans -fga /dev/netdde /hurd/netdde
</pre></td></tr></table>

<p>
and then kill any devnode and pfinet process to let them restart with the newer
netdde. If it still does not work, please post in a bug report the full output of the netdde settrans
above, as well as the output of <code>lspci</code> and <code>lspci -n</code> .
</p>

<p>
To configure the network without going through <tt>/etc/network/interfaces</tt>,
the pfinet translator must be configured.
This can be done by using <code>dhclient</code> from the
<code>isc-dhcp-client</code> package.
This can also be done by hand by using <code>inetutils-ifconfig</code>
from the <code>inetutils-tools</code> package, and <code>ping</code> is
available in the <code>inetutils-ping</code> package.
Last but not least, this can be done (and recorded for good) by hand using the
<code>settrans</code> command to attach a translator to a given
filesystem node. When programs access the node by, for example sending an RPC,
the operating system will transparently start the server to handle the request.
</p>

<table><tr><td>&nbsp;</td><td class=example><pre>
 \# settrans -fgap /servers/socket/2 /hurd/pfinet -i /dev/eth0 \
   -a a.b.c.d -g e.f.g.h -m i.j.k.l
</pre></td></tr></table>

<p>
Here, <code>settrans</code> is passed several options. The first two,
<q><var>fg</var></q>, force any existing translator to go away. The next two,
<q><var>ap</var></q>, make both active and passive translators. By making the
translator active, we will immediately see any error messages on
<tt><q>stderr</q></tt>. The latter saves the translator and arguments in the node
so it can be transparently restarted later (i.e. making the setting persistent
across reboots). The options are followed by the node to which the translator
is to be attached, then the program (i.e. translator) to run and any arguments
to give it. The <q><var>-i</var></q> option is the interface <code>pfinet</code>
will listen on, <q><var>-a</var></q> is the IP address, <q><var>-g</var></q> is the
gateway and <q><var>-m</var></q> is the network mask.
</p>

<p>
Be sure to add name servers to your <tt><q>/etc/resolv.conf</q></tt> file:
</p>

<table><tr><td>&nbsp;</td><td class=example><pre>
  nameserver 192.168.1.1
</pre></td></tr></table>

<p>
To test the configuration, <code>ping -c2 gateway</code>. The
<q><var>-c</var></q> is important to limit the number of pings; recall,
<kbd>CONTROL-C</kbd> does not work in single user mode.
</p>

<p>
Help on <code>settrans</code> can be obtained by passing it the
<q><var>--help</var></q> option. Help on a specific translator can be gotten by
invoking it from the command line with the same argument, e.g.:
</p>

<table><tr><td>&nbsp;</td><td class=example><pre>
 \# /hurd/pfinet --help
</pre></td></tr></table>

<p>
As there can be a lot of output, consider piping this through a pager such as
<code>less</code>.
</p>

<p>
To also configure IPv6 support, the same configuration has to be recorded on
both <tt>/servers/socket/2</tt> and <tt>/servers/socket/26</tt>, referencing
each other so that only one is actually started, bound to both nodes:
</p>

<table><tr><td>&nbsp;</td><td class=example><pre>
 \# settrans -fgap /servers/socket/2 /hurd/pfinet -6 /servers/socket/26 -i /dev/eth0 \
   -a a.b.c.d -g e.f.g.h -m i.j.k.l
 \# settrans -p /servers/socket/26 /hurd/pfinet -4 /servers/socket/2 -i /dev/eth0 \
   -a a.b.c.d -g e.f.g.h -m i.j.k.l
</pre></td></tr></table>

<p>
The pfinet server enables IPv6 autoconfiguration by default. The current status
can be obtained from <tt>fsysopts /servers/socket/26</tt>.  Addresses can also
be set by hand, by using e.g. <tt>-A 2001:123:123::42/64 -G 2001:123:123::1</tt>.
</p>

<p>
The configuration of pfinet can also be changed live
(without record on disk) by using <tt>fsysopts</tt>:
</p>

<table><tr><td>&nbsp;</td><td class=example><pre>
 \# fsysopts /servers/socket/2
 /hurd/pfinet --interface=/dev/eth0 --address=10.3.0.1 --netmask=255.255.0.0 --gateway=10.3.0.128
 \# fsysopts /server/socket/2 -a 10.3.0.2 -m 255.255.0.0 -g 10.3.0.128
</pre></td></tr></table>

<p>
A firewall can be set up by interposing the <tt>eth-filter</tt> translator, for instance, this prevents access to port 22:
</p>

<table><tr><td>&nbsp;</td><td class=example><pre>
 \# settrans -c /dev/eth0f /hurd/eth-filter -i /dev/eth0 -r "not port 22"
</pre></td></tr></table>

<p>
The filtered device, <tt>/dev/eth0f</tt>, can then be given to <tt>pfinet</tt>
or <tt>dhclient</tt> instead of /dev/eth0.
</p>


<h3> Keyboard layout </h3>

<p>
The layout of the keyboard can be configured through the standard
<code>keyboard-configuration</code> package. Make sure that it is installed, and
run <code>dpkg-reconfigure keyboard-configuration</code>. Only the layout is
supported, variants are not (yet). The effect will not
be immediate, as the console needs to be restarted to take the parameter into
account. Rebooting should be fine for instance.
</p>

<h3> Other File Systems </h3>

<p>
Next, edit <tt><q>/etc/fstab</q></tt> to add any additional filesystems as well as
swap space. It is <em>very important</em> 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 but will happily page to any device including
a raw partition such as your home partition. By default, <code>nano</code> and <code>vi</code> are
the only editors installed by the base distribution.
</p>

<p>
Here is an example <tt><q>/etc/fstab</q></tt> file:
</p>

<table><tr><td>&nbsp;</td><td class=example><pre>
\# &#60;file system&#62; &#60;mount point&#62;   &#60;type&#62;  &#60;options&#62;  &#60;dump&#62;  &#60;pass&#62;
/dev/hd0s1      /               ext2    rw         0       1
/dev/hd0s2      /home           ext2    rw         0       2
/dev/hd0s3      none            swap    sw         0       0
</pre></td></tr></table>

<p>
If any <code>/dev</code> device entry is missing, remember to create it using the <code>MAKEDEV</code> command:
</p>

<table><tr><td>&nbsp;</td><td class=example><pre>
 \# cd /dev
 \# ./MAKEDEV hd0s1 hd0s2 hd0s3
</pre></td></tr></table>

<p>
You can also mount a filesystem by hand by calling <code>settrans</code>:
</p>

<table><tr><td>&nbsp;</td><td class=example><pre>
 \# settrans /mnt /hurd/ext2fs /dev/hd0s5
</pre></td></tr></table>

<p>
The idea behind this command is that you set on the <code>/mnt</code> node the
<code>/hurd/ext2fs /dev/hd0s5</code> translator. <code>/hurd/ext2fs</code> will
get executed and start read/writing <code>/dev/hd0s5</code> and show its content
on <code>/mnt</code>. More information can be found in the
<a href="hurd-doc-translator">Translator documentation</a>.
</p>

<p>
To mount an nfs filesystem, <code>/hurd/nfs</code> translator is used. When
run as non-root, the translator will connect to the server using a port above
1023. By default, GNU/Linux will reject this. To tell GNU/Linux to accept
connections originating from a non-reserved port, add the
<q><var>insecure</var></q> option to the export line. Here is an example
<tt><q>/etc/exports</q></tt> file assuming the client's ip address is
<tt><q>192.168.1.2</q></tt>:
</p>

<table><tr><td>&nbsp;</td><td class=example><pre>
  /home  192.168.1.2(rw,insecure)
</pre></td></tr></table>

<p>
To mount this from a GNU box and assuming that nfs server's ip address is
<tt><q>192.168.1.1</q></tt>:
</p>

<table><tr><td>&nbsp;</td><td class=example><pre>
\# settrans -cga /mount/point /hurd/nfs 192.168.1.1:/home
</pre></td></tr></table>


<h2> Have fun with Debian GNU/Hurd </h2>

<p>
Now, what nice things can we do with the Hurd?
</p>

<h3> Mount disk images </h3>

<p>
Accessing the content of a CD image is a bit tedious with standard Unix systems
if you are not root. On GNU/Hurd, it amounts to this:
</p>

<table><tr><td>&nbsp;</td><td class=example><pre>
settrans ~/mnt /hurd/iso9660fs CD_image.iso
</pre></td></tr></table>

<p>
And it is completely safe: the <code>iso9660fs</code> translator is running
under your identity, not root. You can even code your own translator for any
kind of filesystem. Yes, this is like FUSE. Without all the kludge.
</p>

<h3> Transparent FTP </h3>

<p>
The following sets up a transparent <code>ftp</code> directory:
</p>

<table><tr><td>&nbsp;</td><td class=example><pre>
settrans -c /ftp: /hurd/hostmux /hurd/ftpfs /
</pre></td></tr></table>

<p>
Now, <code>cd</code> to e.g. <code>/ftp://ftp.gnu.org/</code>, and run <code>ls</code> there.
Yes, you can from your home simply run <code>tar xf ftp://ftp.gnu.org/pub/gnu/gcc/gcc-4.6.0/gcc-4.6.0.tar.bz2</code> !
</p>

<h3> Sub-Hurd </h3>

<p>
A <a href="https://www.gnu.org/software/hurd/hurd/subhurd.html">sub-Hurd</a> is a
complete subsystem. Very much like virtualization containers on first
sight. Except that you do not need to be root at all to run one.
</p>

<h3> gdb ext2fs, pfinet, ... </h3>

<p>
Yes, you can run gdb on e.g. the ext2fs implementation, the <code>pfinet</code> TCP/IP stack, etc.
</p>

<h3> And many more things! </h3>

<p>
Some in-progress work include <code>mboxfs</code>, <code>tarfs</code>, <code>xmlfs</code>, <code>gopherfs</code>, ...
</p>

#<h3> 7.3 Rebooting </h3>
#
#<p>
#Finally, reboot into multiuser mode, i.e. in the same way single user mode was
#brought up minus the <q><var>-s</var></q> option when loading the kernel. For
#details, see section 5. Booting GNU/Hurd.
#</p>
#
#<p>
#Happy Hacking!
#</p>

<h2>Final Words </h2>

<p>
The following are just install-time quickies, make sure to also read
documentation for the installed system: the <a href=hurd-doc>Debian GNU/Hurd documentation</a>,
but also the <a href=http://hurd.gnu.org/>Upstream website</a>.
</p>


#<h3> 8.1 The Grub Menu </h3>
#
#<p>
#Having to always load the kernel by hand can be very tedious. Edit the
#<tt><q>/boot/grub/menu.lst</q></tt> for Grub1 or
#<tt><q>/boot/grub/grub.cfg</q></tt> for Grub2 and tailor it appropriately;
#booting will become much quicker and easier.
#</p>
#
#
#<h3> 8.2 Adding Devices </h3>
#
#<p>
#By default, only a few devices are created in the <tt><q>/dev</q></tt> directory.
##Use the <code>MAKEDEV</code> script to create any needed device nodes.
#</p>

<h3><a name=morepackages> Installing More Packages </a></h3>

<p>
There are several ways to add packages. Downloading and using
<code>dpkg -i</code> works but is very inconvenient. The easiest method
is to use <code>apt</code>.
</p>

<p>
If you have used the Debian GNU/Hurd 2023 release, the safest
way is use the snapshot of this release as apt source: edit
<tt><q>/etc/apt/sources.list</q></tt>, add the following unreleased entry.
</p>

<table><tr><td>&nbsp;</td><td class=example><pre>
deb [check-valid-until=no trusted=yes] https://snapshot.debian.org/archive/debian-ports/20230606T000000Z/ sid main
deb [check-valid-until=no trusted=yes] https://snapshot.debian.org/archive/debian-ports/20230606T000000Z/ unreleased main
deb-src [check-valid-until=no trusted=yes] https://snapshot.debian.org/archive/debian/20230606T000000Z/ sid main
</pre></td></tr></table>

<p>
Update, install the <code>debian-ports-archive-keyring</code> package, and update again, you now have the
full Debian GNU/Hurd 2023 release available.
</p>


<p>
If you have used a snapshot later than the 2023 release, you can add these
sources to get the most recent packages:
</p>

<table><tr><td>&nbsp;</td><td class=example><pre>
deb http://deb.debian.org/debian-ports unstable main
deb-src http://deb.debian.org/debian unstable main
deb http://deb.debian.org/debian-ports unreleased main
</pre></td></tr></table>

<p>
Update, install the <code>debian-ports-archive-keyring</code> package, and
update again.
</p>

<p>
If when doing your first <code>apt</code>, <code>dpkg</code> complains of
missing programs, get root in a login shell (i.e. <code>su -</code>, not just
<code>su</code>).
</p>

<p>
If GNU Mach does not recognize your network card or you use a modem, the only
way to upgrade will be to download the packages and then transfer them to the
GNU system. The easiest way to do this is to use apt off-line. Refer to
<tt><q>/usr/share/doc/apt-doc/offline.text.gz</q></tt> for detailed instructions.
</p>


<h3>The Hurd console</h3>

<p>
Besides the Mach console you encountered during installation, the GNU/Hurd
features a powerful user-space console providing virtual terminals.
If you have installed in pseudo-graphical mode, it should be started
automatically at boot, otherwise you can start it manually with the following
command:
</p>

<table><tr><td>&nbsp;</td><td class=example><pre>
 \# console -d vga -d pc_mouse --repeat=mouse -d pc_kbd --repeat=kbd -d generic_speaker -c /dev/vcs
</pre></td></tr></table>

<p>
If it is confirmed to be working, it can be enabled at boot from
<tt>/etc/default/hurd-console</tt>: turn <tt>ENABLE="false"</tt> into
<tt>ENABLE="true"</tt>.
</p>

<p>
Inside the Hurd console, you can switch between virtual terminals via
<kbd>ALT+F1</kbd>, <kbd>ALT+F2</kbd> and so on. <kbd>ALT+CTRL+BACKSPACE</kbd> detachs
the Hurd console and brings you back to the Mach console, from where you
can reattach again with the above command.
</p>


<h3>X.Org </h3>

<p>
X.Org has been ported and all video cards, which it supports that do not
require a kernel module or drm should work.
</p>

<p>
You need to already be running the Hurd console and have repeaters setup as
indicated in the previous section. For instance, check that <code>echo
$TERM</code> prints <code>hurd</code>, and check that <code>/dev/cons/kbd</code>
and <code>/dev/cons/mouse</code> exist.
</p>

<p>
You need to run <tt>dpkg-reconfigure x11-common xserver-xorg-legacy</tt> to allow any user to start
Xorg, because the X wrapper does not know about the Hurd and Mach consoles.
</p>

<p>
You also need to create a <tt>/etc/X11/xorg.conf</tt> to enable the control-alt-backspace shortcut:
</p>

<table><tr><td>&nbsp;</td><td class=example><pre>
Section "InputDevice"
   Identifier "Generic Keyboard"
   Driver "kbd"
   Option "XkbOptions" "terminate:ctrl_alt_bksp"
EndSection
</pre></td></tr></table>

<p>
It may happen that for some reason Xorg chooses a 16/9 resolution but a 4/3 desktop size. Blame Xorg, not the Hurd :) To avoid the issue, append this to <tt>/etc/X11/xorg.conf</tt> :
</p>

<table><tr><td>&nbsp;</td><td class=example><pre>
Section "Screen"
   Identifier "myScreen"
   SubSection "Display"
      Virtual 1024 768
   EndSubSection
EndSection
</pre></td></tr></table>

<p>
You will need several X packages. <code>xorg</code>,
<code>rxvt</code> and a window manager: <code>twm</code>, <code>icewm</code>, <code>openbox</code>, ...
are a good start. If you want X to get started at boot, you have to install a
display manager. <code>lightdm</code> and <code>gdm</code> do not work yet, but
<code>xdm</code> should just work fine.
</p>

<p>
Finally, run <code>startx /usr/bin/yourwm</code>
</p>

<p>
If that doesn't work, as mentioned by the error message, look in <tt>/var/log/Xorg.0.log</tt> (or post it to the list for people to have a look).
</p>

<h3>Upgrading your System</h3>

<p>
If you are using a Debian release snapshot, you will not have any upgrade
available, since the released distribution is frozen at the release date.
<b>This means you will not get security updates!</b> You may rather want to
enable the unstable distribution as described in section
<a href=#morepackages>Installing More Packages</a>.
</p>

<p>
Once you have enabled the unstable distribution, note that since this is
unstable, it is affected by library transition hickups, so do not be surprised
that it will sometimes not be able to upgrade some packages. Generally, you can
use the recommended Debian upgrade procedure: first use
</p>

<table><tr><td>&nbsp;</td><td class=example><pre>
\# apt upgrade --without-new-pkgs
</pre></td></tr></table>

<p>to upgrade what can be without changing the list of packages, and then use</p>

<table><tr><td>&nbsp;</td><td class=example><pre>
\# apt full-upgrade
</pre></td></tr></table>

<p>to upgrade the rest.</p>

<p>Note: if you very seldomly upgrade your system, you may hit upgrade
issues. Make sure to first upgrade to the latest release snapshot (Hurd 2023,
see section <a href=#morepackages>Installing More Packages</a>) before upgrading
from the unstable distribution.</p>

<h3>Last words</h3>

<p>
To shutdown your system, simply use <code>halt</code>, <code>poweroff</code> or <code>reboot</code>. If that happens to sometimes hang because some daemon is not terminating properly, you can use instead <code>halt-hurd</code>, <code>poweroff-hurd</code>, <code>reboot-hurd</code>, which don't actually shut down daemons, but properly sync data to disk.
</p>