Debian -- Debian GNU/Hurd — Configuratio

Debian -- Debian GNU/Hurd — Configuration
Skip Quicknav
Blog
Micronews
Planet
Wiki
Ports
Debian GNU/Hurd
Debian GNU/Hurd — Configuration
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.
Overview
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.
Installation
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 2G -drive file=$(echo debian-hurd*.img),cache=writeback
(or
for the 64-bit pre-release)
To enable accessing the box through ssh, you can append
-net nic -net user,hostfwd=tcp:127.0.0.1:2222-:22
and ssh to your local TCP port 2222.
You can also convert the image to the VDI format for virtualbox (but running inside virtualbox is not really tested, so you are on your own and may encounter issues that don't happen with qemu/kvm):
$ VBoxManage convertfromraw debian-hurd-*.img debian-hurd.vdi --format vdi
Configuration
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:
nameserver 192.168.1.1
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=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
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:
#
/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
192.168.1.2
/home 192.168.1.2(rw,insecure)
To mount this from a GNU box and assuming that nfs server's ip address is
192.168.1.1
# settrans -cga /mount/point /hurd/nfs 192.168.1.1:/home
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
Sub-Hurd
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 2025 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/20250807T000000Z/ sid main
deb [check-valid-until=no trusted=yes] https://snapshot.debian.org/archive/debian-ports/20250807T000000Z/ unreleased main
deb-src [check-valid-until=no trusted=yes] https://snapshot.debian.org/archive/debian/20250807T000000Z/ sid main
Update, install the
debian-ports-archive-keyring
package, and update again, you now have the
full Debian GNU/Hurd 2025 release available.
You can then also 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
detaches
the Hurd console and brings you back to the Mach console, from where you
can reattach again with the above command.
X.Org
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"
EndSection
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
EndSubSection
EndSection
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 seldom upgrade your system, you may hit upgrade
issues. Make sure to first upgrade to the latest release snapshot (Hurd 2025,
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.
Back to the
Debian Project homepage
This page is also available in the following languages:
How to set
the default document language
About
Social Contract
Code of Conduct
Free Software
Legal Info
Help Debian
Getting Debian
Network install
CD/USB ISO images
Pure Blends
Debian Packages
Developers' Corner
News
Project News
Events
Documentation
Release Info
Debian Wiki
Support
Debian International
Security Information
Bug reports
Mailing Lists
The Debian Blog
Debian Micronews
Debian Planet
See our
contact page
to get in touch. Web site source code is
available
Last Modified: Sat, Aug 9 23:24:14 UTC 2025