Ports ] [ Debian GNU/Hurd ] [ News ] [ Configuration ] [ Hurd CDs ] [ Documentation ] [ Development ] [ Contact ]

Debian GNU/Hurd Configuration

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.

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


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 Not Unix. 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 mount point. 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.

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.

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.


You can simply use the Debian installer, see the prepared CD images. Then the following steps will be needed for proper configuration.

You can also get a pre-installed image and run it in qemu:

$ 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

To enable accessing the box through ssh, you can append

-net nic -net user,hostfwd=tcp:

and ssh to your local TCP port 2222.

You can also convert the image to the VDI format for virtualbox:

$ VBoxManage convertfromraw debian-hurd-*.img debian-hurd.vdi --format vdi


The Network

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

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

 # settrans -fga /dev/netdde /hurd/netdde

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 lspci and lspci -n .

To configure the network without going through /etc/network/interfaces, the pfinet translator must be configured. This can be done by using dhclient from the isc-dhcp-client package. This can also be done by hand by using inetutils-ifconfig from the inetutils-tools package, and ping is available in the inetutils-ping package. Last but not least, this can be done (and recorded for good) by hand using the settrans 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.

 # 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

Here, settrans is passed several options. The first two, fg, force any existing translator to go away. The next two, ap, make both active and passive translators. By making the translator active, we will immediately see any error messages on stderr. 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 -i option is the interface pfinet will listen on, -a is the IP address, -g is the gateway and -m is the network mask.

Be sure to add name servers to your /etc/resolv.conf file:


To test the configuration, ping -c2 gateway. The -c is important to limit the number of pings; recall, CONTROL-C does not work in single user mode.

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

 # /hurd/pfinet --help

As there can be a lot of output, consider piping this through a pager such as less.

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

 # 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

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

The configuration of pfinet can also be changed live (without record on disk) by using fsysopts:

 # fsysopts /servers/socket/2
 /hurd/pfinet --interface=/dev/eth0 --address= --netmask= --gateway=
 # fsysopts /server/socket/2 -a -m -g

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

 # settrans -c /dev/eth0f /hurd/eth-filter -i /dev/eth0 -r "not port 22"

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

Keyboard layout

The layout of the keyboard can be configured through the standard keyboard-configuration package. Make sure that it is installed, and run dpkg-reconfigure keyboard-configuration. 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.

Other File Systems

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

Here is an example /etc/fstab file:

# <file system> <mount point>   <type>  <options>  <dump>  <pass>
/dev/hd0s1      /               ext2    rw         0       1
/dev/hd0s2      /home           ext2    rw         0       2
/dev/hd0s3      none            swap    sw         0       0

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

 # cd /dev
 # ./MAKEDEV hd0s1 hd0s2 hd0s3

You can also mount a filesystem by hand by calling settrans:

 # settrans /mnt /hurd/ext2fs /dev/hd0s5

The idea behind this command is that you set on the /mnt node the /hurd/ext2fs /dev/hd0s5 translator. /hurd/ext2fs will get executed and start read/writing /dev/hd0s5 and show its content on /mnt. More information can be found in the Translator documentation.

To mount an nfs filesystem, /hurd/nfs 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 insecure option to the export line. Here is an example /etc/exports file assuming the client's ip address is


To mount this from a GNU box and assuming that nfs server's ip address is

# settrans -cga /mount/point /hurd/nfs

Have fun with Debian GNU/Hurd

Now, what nice things can we do with the Hurd?

Mount disk images

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:

settrans ~/mnt /hurd/iso9660fs CD_image.iso

And it is completely safe: the iso9660fs 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.

Transparent FTP

The following sets up a transparent ftp directory:

settrans -c /ftp: /hurd/hostmux /hurd/ftpfs /

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


A sub-Hurd 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.

gdb ext2fs, pfinet, ...

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

And many more things!

Some in-progress work include mboxfs, tarfs, xmlfs, gopherfs, ...

Final Words

The following are just install-time quickies, make sure to also read documentation for the installed system: the Debian GNU/Hurd documentation, but also the Upstream website.

Installing More Packages

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

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

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

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

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

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

Update, install the debian-ports-archive-keyring package, and update again.

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

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 /usr/share/doc/apt-doc/offline.text.gz for detailed instructions.

The Hurd console

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:

 # console -d vga -d pc_mouse --repeat=mouse -d pc_kbd --repeat=kbd -d generic_speaker -c /dev/vcs

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

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


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

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

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

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

Section "InputDevice"
   Identifier "Generic Keyboard"
   Driver "kbd"
   Option "XkbOptions" "terminate:ctrl_alt_bksp"

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 /etc/X11/xorg.conf :

Section "Screen"
   Identifier "myScreen"
   SubSection "Display"
      Virtual 1024 768

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

Finally, run startx /usr/bin/yourwm

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

Upgrading your System

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. This means you will not get security updates! You may rather want to enable the unstable distribution as described in section Installing More Packages.

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

# apt upgrade --without-new-pkgs

to upgrade what can be without changing the list of packages, and then use

# apt full-upgrade

to upgrade the rest.

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 Installing More Packages) before upgrading from the unstable distribution.

Last words

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