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

Debian GNU/Hurd

Dirk Ritter sent me the following text, which contains the output of the --help option of every Hurd server program. This may be a good starting point for further documentation of the server programs, especially those useful to a user, like ext2fs, ufs, isofs, ftpfs, crash, etc.

Since then, I updated the text using mail excerpts from the Hurd mailing lists. Thanks to Martin von Loewis.

Preliminary GNU/Hurd User Interface Description

Currently there is next to nothing but this might be better than nothing at all, so please send complaints, corrections and additions to Dirk Ritter, <dirk@gnumatic.s.bawue.de>. Please note that my programming skills are very limited, so you should not expect me to actually understand anything related to Operating Systems design and implementations.

Index of HURD servers and translators:
The authentication server "auth"
The crash server "crash"
The exec server "exec"
The ext2fs server "ext2fs"
The fifo translator "fifo"
The firmlink translator "firmlink"
The ftp filesystem translator "ftpfs"
The fwd server "fwd"
The hostmux server "hostmux"
The ifsock server "ifsock"
The init server "init"
The iso filesystem server "isofs"
The magic server "magic"
The new-fifo server "new-fifo"
The nfs server "nfs"
The null server "null"
The pfinet server "pfinet"
The pflocal server "pflocal"
The process server "proc"
The storage translator "storeio"
The symbolic link translator "symlink"
The terminal server "term"
The ufs server "ufs"
The usermux server "usermux"

The authentication server - "auth"

Passes credentials when two mutually untrusting servers communicate. In a sense, each auth server establishes a domain of trust. (Martin von Loewis, 10 Oct 1996)

One of its interesting features is that it makes it possible for processes to impersonate several identities at the same time, and also to dynamically acquire or relinquish identities.

Running "/hurd/auth --help" gives:

Usage: auth [OPTION...]

  -?, --help                 Give this help list
      --usage                Give a short usage message
  -V, --version              Print program version

Report bugs to bug-hurd@gnu.org.

The crash server - "crash"

The crash server gets active whenever a task gets a fatal error signal, for example because it violates memory boundaries (segmentation fault). The crash server has three modes of operation: suspending the process group (pgrp) of the offending task, killing it or dumping a core file. The latter is not yet implemented. Think of the crash server of an airbag.

You can set the mode of operation with settrans of course, but also with fsysopts at runtime. This is true for the system wide default and usually requires root privileges. A user can select a different default with the CRASHSERVER environment variable. You set this variable to an inode that has the crash server attached to it. On a default Debian GNU/Linux system, there three default operations have corresponding translators in /servers/crash-*.


 These options specify the disposition of a crashing process:
  -s, --suspend              Suspend the process
  -k, --kill                 Kill the process
  -c, --core-file            Dump a core file
      --dump-core

The execute server - "exec"

Exec manages the creation of a new process image from the image file.

Actually this server has support to create a runnable process image out of any image file recognized by the BFD library (this includes a.out, ELF, and many others). Gzipped executable are also recognized (useful for boot floppies).

Running "/hurd/exec --help" gives:

Usage: exec [OPTION...]
Hurd standard exec server

  -?, --help                 Give this help list
      --usage                Give a short usage message
  -V, --version              Print program version

Report bugs to bug-hurd@gnu.org.

The ext2 filesystem server - "ext2fs"

This server manages ext2-type filesystems. It does the same as ext2fs.static, only that ext2fs.static is a statically linked executable.

Running "/hurd/ext2fs --help" gives:

Usage: ext2fs [OPTION...] DEVICE...

If neither --interleave or --layer is specified, multiple DEVICEs are
concatenated.

  -E, --no-exec              Don't permit any execution of files on this
                             filesystem
  -I, --interleave=BLOCKS    Interleave in runs of length BLOCKS
  -L, --layer                Layer multiple devices for redundancy
  -n, --no-sync              Don't automatically sync data to disk
  -r, --readonly             Never write to disk or allow opens for writing
  -s, --sync[=INTERVAL]      If INTERVAL is supplied, sync all data not
                             actually written to disk every INTERVAL seconds,
                             otherwise operate in synchronous mode (the default
                             is to sync every 30 seconds)
  -S, --no-suid              Don't permit set-uid or set-gid execution
  -T, --store-type=TYPE      Each DEVICE names a store of type TYPE
  -w, --writable             Use normal read/write behavior

 Boot options:
      --bootflags=FLAGS
  -C, --directory=DIRECTORY
      --device-master-port=PORT
      --exec-server-task=PORT
      --host-priv-port=PORT

  -?, --help                 Give this help list
      --usage                Give a short usage message
  -V, --version              Print program version

Mandatory or optional arguments to long options are also mandatory or optional
for any corresponding short options.

If neither --interleave or --layer is specified, multiple DEVICEs are
concatenated.

Report bugs to bug-hurd@gnu.org.

The fifo server - "fifo"

The fifo translator implements named pipes.

Running "/hurd/fifo --help" gives:

Usage: fifo [OPTION...]
Translator for fifos

  -d, --dgram                Reads reflect write record boundaries
  -m, --multiple-readers     Allow multiple simultaneous readers
  -n, --noblock              Don't block on open
  -?, --help                 Give this help list
      --usage                Give a short usage message
  -V, --version              Print program version

Report bugs to bug-hurd@gnu.org.

The firmlink server - "firmlink"

A translator for firmlinks.

Running "/hurd/firmlink --help" gives:

Usage: firmlink [OPTION...] TARGET
A translator for firmlinks

  -?, --help                 Give this help list
      --usage                Give a short usage message
  -V, --version              Print program version

A firmlink is sort of half-way between a symbolic link and a hard link;

Like a symbolic link, it is `by name', and contains no actual reference to the
target.  However, the lookup returns a node which will redirect parent lookups
so that attempts to find the cwd that go through the link will reflect the link
name, not the target name.  The target referenced by the firmlink is looked up
in the namespace of the translator, not the client.

Report bugs to bug-hurd@gnu.org.

The ftp filesystem server - "ftpfs"

A server for ftp filesystems.

Running "/hurd/ftpfs --help" gives:

Usage: ftpfs [OPTION...] REMOTE_FS [SERVER]
Hurd ftp filesystem translator

  -D, --debug[=FILE]         Print debug output to FILE

 Parameters:
      --bulk-stat-period=SECS   Period for detecting bulk stats (default 10)
      --bulk-stat-threshold=SECS   Number of stats within the bulk-stat-period
                             that trigger a bulk stat (default 5)
      --name-timeout=SECS    Time directory names are cached (default 300)
      --node-cache-size=ENTRIES   Number of recently used filesystem nodes that
                             are cached (default 50)
      --stat-timeout=SECS    Time stat information is cached (default 120)

  -?, --help                 Give this help list
      --usage                Give a short usage message

Mandatory or optional arguments to long options are also mandatory or optional
for any corresponding short options.

If SERVER is not specified, an attempt is made to extract it from REMOTE_FS,
using `SERVER:FS' notation.  SERVER can be a hostname, in which case anonymous
ftp is used, or may include a user and password like `USER:PASSWORD@HOST' (the
`:PASSWORD' part is optional).

Report bugs to bug-hurd@gnu.org.

The fwd server - "fwd"

When accessed, the fwd translator forwards requests to another server. It is used in the fifo and symlink server. The idea is so that you don't get a jillion servers for such trivial things; fwd is used to coordinate having one server handle several different nodes conveniently.

Running "/hurd/fwd --help" gives:

Usage: /hurd/fwd SERVER [TRANS_NAME [TRANS_ARG...]]

The hostmux server - "hostmux"

I have no idea what this server is good for. (A server for host lookups?)

Running "/hurd/hostmux --help" gives:

Usage: hostmux [OPTION...] TRANSLATOR [ARG...]
A translator for invoking host-specific translators

  -H, --host-pattern=PAT     The string to replace in the translator
                             specification with the hostname; if empty, or
                             doesn't occur, the hostname is appended as
                             additional argument instead (default `${host}')
  -?, --help                 Give this help list
      --usage                Give a short usage message

Mandatory or optional arguments to long options are also mandatory or optional
for any corresponding short options.

This translator appears like a directory in which hostnames can be looked up,
and will start TRANSLATOR to service each resulting node.

Report bugs to bug-hurd@gnu.org.

The ifsock server - "ifsock"

ifsock only handles S_IFSOCK filesystem nodes for filesystems which don't do it themselves, acting as a hook upon which to hang Unix domain socket addresses. pfinet and pflocal implement the socket API. (Thomas Bushnell, 10 Oct 1996)

Running "/hurd/ifsock --help" gives:

/hurd/ifsock: Must be started as a translator

The initialisation server - "init"

A server for system boot procedures and basic runtime configurations.

Running "/hurd/init --help" gives:

Usage: init [OPTION...]
Start and maintain hurd core servers and system run state

  -d, --debug
  -f, --fake-boot            This hurd hasn't been booted on the raw machine
  -n, --init-name
  -q, --query                Ask for the names of servers to start
  -s, --single-user          Startup system in single-user mode
  -?, --help                 Give this help list
      --usage                Give a short usage message
  -V, --version              Print program version

Report bugs to bug-hurd@gnu.org.

The iso filesystem server - "isofs"

A server for iso-type filesystems, commonly used on compact disks.

Running "/hurd/isofs --help" gives:

Usage: isofs [OPTION...] DEVICE...

If neither --interleave or --layer is specified, multiple DEVICEs are
concatenated.

  -E, --no-exec              Don't permit any execution of files on this
                             filesystem
  -I, --interleave=BLOCKS    Interleave in runs of length BLOCKS
  -L, --layer                Layer multiple devices for redundancy
  -n, --no-sync              Don't automatically sync data to disk
  -r, --readonly             Never write to disk or allow opens for writing
  -s, --sync[=INTERVAL]      If INTERVAL is supplied, sync all data not
                             actually written to disk every INTERVAL seconds,
                             otherwise operate in synchronous mode (the default
                             is to sync every 30 seconds)
  -S, --no-suid              Don't permit set-uid or set-gid execution
  -T, --store-type=TYPE      Each DEVICE names a store of type TYPE
  -w, --writable             Use normal read/write behavior

 Boot options:
      --bootflags=FLAGS
  -C, --directory=DIRECTORY
      --device-master-port=PORT
      --exec-server-task=PORT
      --host-priv-port=PORT

  -?, --help                 Give this help list
      --usage                Give a short usage message
  -V, --version              Print program version

Mandatory or optional arguments to long options are also mandatory or optional
for any corresponding short options.

If neither --interleave or --layer is specified, multiple DEVICEs are
concatenated.

Report bugs to bug-hurd@gnu.org.

The magic server - "magic"

A translator that returns the magic retry result MAGIC. Normal end users probably need not to know much about it since it is used, for example, to facilitate terminal I/O. Programmers might benefit from the following pieces of information Thomas Bushnell gave:

The key here is to know what a "magic retry result" is. The thing to do is to look at the dir_lookup RPC documented in <hurd/fs.defs> and <hurd/hurd_types.defs>.
Magic lookup results are basically for cases where the lookup needs information that is part of the calling process's state, and not part of the normal name lookup procedure. These "punt to caller's state" things have to each be implemented specially in the C library (see libc/hurd/hurdlookup.c), and cover the known cases to provide the functionality that many other systems provide.

He also kindly explained a particular behavior that usually puzzles normal end users when they first encounter it:

The inability to "ls /dev/fd" is because the translator doesn't know what file descriptors you have open, so it can't tell you which ones exist. But the behavior of it is exactly as on other systems.

Running "/hurd/magic --help" gives:

Usage: magic [OPTION...] MAGIC
A translator that returns the magic retry result MAGIC

  -?, --help                 Give this help list
      --usage                Give a short usage message
  -V, --version              Print program version

Report bugs to bug-hurd@gnu.org.

The new-fifo server - "new-fifo"

Alternative server for named pipes.

Running "/hurd/new-fifo --help" gives:

Usage: new-fifo [OPTION...]

  -d, --dgram                Reflect write record boundaries
  -n, --noblock              Don't block on open
  -r, --multiple-readers     Allow multiple simultaneous readers
  -s, --server               Operate in server mode
  -S, --standalone           Don't attempt to use a fifo server
  -U, --use-server=NAME      Attempt use server NAME
  -?, --help                 Give this help list
      --usage                Give a short usage message

Mandatory or optional arguments to long options are also mandatory or optional
for any corresponding short options.

Report bugs to bug-hurd@gnu.org.

The network filesystem server - "nfs"

Network file system support for Sun's Network File System.

Running "/hurd/nfs --help" gives:

Usage: nfs [OPTION...] REMOTE_FS [HOST]
Hurd nfs translator

  -h, --hard                 Retry file systems requests until they succeed
  -s, --soft[=RETRIES]       File system requests will eventually fail, after
                             RETRIES tries if specified, otherwise 3
  -R, --read-size=BYTES, --rsize=BYTES
                             Max packet size for reads (default 8192)
  -W, --write-size=BYTES, --wsize=BYTES
                             Max packet size for writes (default 8192)

 Timeouts:
      --cache-timeout=SEC    Timeout for cached file data (default 3)
      --init-transmit-timeout=SEC
      --max-transmit-timeout=SEC
      --name-cache-neg-timeout=SEC
                             Timeout for negative directory cache entries
                             (default 3)
      --name-cache-timeout=SEC   Timeout for positive directory cache entries
                             (default 3)
      --stat-timeout=SEC     Timeout for cached stat information (default 3)

 Server specification:
      --default-mount-port=PORT   Port for mount server, if none can be found
                             automatically
      --default-nfs-port=PORT   Port for nfs operations, if none can be found
                             automatically
      --mount-port=PORT      Port for mount server
      --mount-program=ID[.VERS]
      --nfs-port=PORT        Port for nfs operations
      --nfs-program=ID[.VERS]
      --pmap-port=SVC|PORT

  -?, --help                 Give this help list
      --usage                Give a short usage message

Mandatory or optional arguments to long options are also mandatory or optional
for any corresponding short options.

If HOST is not specified, an attempt is made to extract it from REMOTE_FS,
using either the `HOST:FS' or `FS@HOST' notations.

Report bugs to bug-hurd@gnu.org.

The kitchen sink - "null"

A server for lots of free space and countless numbers of zeroes, implements /dev/null and /dev/zero.

Running "/hurd/null --help" gives:

Usage: null [OPTION...]
Endless sink and null source

  -?, --help                 Give this help list
      --usage                Give a short usage message
  -V, --version              Print program version

Report bugs to bug-hurd@gnu.org.

The TCP/IP server - "pfinet"

A server for TCP/IP, which implements the (IPv4) PF_INET protocol family. The server which will implement the IPv6 protocol family would be called pfinet6 in the current scheme.

Setting this up isn't hard at all. It always is placed in /servers/socket/2, because that's where glibc will look for it. So be sure to install it this way: settrans /servers/socket/2 /hurd/pfinet -6 /servers/socket/26 --interface=/dev/eth0 OPTIONS and settrans /servers/socket/26 /hurd/pfinet -4 /servers/socket/2 --interface=/dev/eth0 OPTIONS, where OPTIONS specify your IP address, netmask and the gateway (if any). Only one network interface is supported currently. Later, you can also set further interfaces like eth1 and so on with the same command.

If you don't have a network card you should at least install the loopback interface, so localhost works (important for print spooling and other useful stuff). Do this with the above command, but don't specify any interface or OPTIONS. A simple settrans /servers/socket/1 /hurd/pfinet will do it.

Running "/hurd/pfinet --help" gives:

Swansea University Computer Society TCP/IP for NET3.019
IP Protocols: ICMP, UDP, TCP
Usage: pfinet [OPTION...]
Interface-specific options before the first interface specification apply to
the first following interface; otherwise they apply to the previously specified
interface.

  -i, --interface=DEVICE     Network interface to use

 These apply to a given interface:
  -a, --address=ADDRESS      Set the network address
  -g, --gateway=ADDRESS      Set the default gateway
  -m, --netmask=MASK         Set the netmask
  -s, --shutdown             Shut it down

  -?, --help                 Give this help list
      --usage                Give a short usage message

Mandatory or optional arguments to long options are also mandatory or optional
for any corresponding short options.

Report bugs to bug-hurd@gnu.org.

The pflocal server - "pflocal"

Implements UNIX domain sockets. Needed for pipes, for example.

Running "/hurd/pflocal --help" gives:

Usage: /hurd/pflocal

The process server - "proc"

The proc server assigns PID's and process structures to tasks, and manages all the process level stuff like wait, bits of fork, C library support.

Running "/hurd/proc --help" gives:

Usage: proc [OPTION...]
Hurd process server

  -?, --help                 Give this help list
      --usage                Give a short usage message
  -V, --version              Print program version

Report bugs to bug-hurd@gnu.org.

The storage translator - "storeio"

A translator for devices and other stores.

Running "/hurd/storeio --help" gives:

Usage: storeio [OPTION...] DEVICE...
Translator for devices and other stores

  -I, --interleave=BLOCKS    Interleave in runs of length BLOCKS
  -L, --layer                Layer multiple devices for redundancy
  -n, --rdev=ID              The stat rdev number for this node; may be either
                             a single integer, or of the form MAJOR,MINOR
  -r, --readonly             Disallow writing
  -T, --store-type=TYPE      Each DEVICE names a store of type TYPE
  -w, --writable             Allow writing
  -?, --help                 Give this help list
      --usage                Give a short usage message
  -V, --version              Print program version

Mandatory or optional arguments to long options are also mandatory or optional
for any corresponding short options.

If neither --interleave or --layer is specified, multiple DEVICEs are
concatenated.

Report bugs to bug-hurd@gnu.org.

The symbolic link server - "symlink"

A server for symbolic links for filesystems which don't support it themselves.

Running "/hurd/symlink --help" gives:

?
(There has not been any output? Strange...)

The terminal server - "term"

Implements a POSIX terminal.

Running "/hurd/term --help" gives:

Usage: term ttyname type arg

The ufs server - "ufs"

A server for ufs-type filesystems. It does the same as ufs.static, only that ufs.static is a statically linked executable.

Running "/hurd/ufs --help" gives:

Usage: ufs [OPTION...] DEVICE...

If neither --interleave or --layer is specified, multiple DEVICEs are
concatenated.

  -C, --compat=FMT           FMT may be GNU, 4.4, or 4.2, and determines which
                             filesystem extensions are written onto the disk
                             (default is GNU)
  -E, --no-exec              Don't permit any execution of files on this
                             filesystem
  -I, --interleave=BLOCKS    Interleave in runs of length BLOCKS
  -L, --layer                Layer multiple devices for redundancy
  -n, --no-sync              Don't automatically sync data to disk
  -r, --readonly             Never write to disk or allow opens for writing
  -s, --sync[=INTERVAL]      If INTERVAL is supplied, sync all data not
                             actually written to disk every INTERVAL seconds,
                             otherwise operate in synchronous mode (the default
                             is to sync every 30 seconds)
  -S, --no-suid              Don't permit set-uid or set-gid execution
  -T, --store-type=TYPE      Each DEVICE names a store of type TYPE
  -w, --writable             Use normal read/write behavior

 Boot options:
      --bootflags=FLAGS
      --device-master-port=PORT
      --directory=DIRECTORY
      --exec-server-task=PORT
      --host-priv-port=PORT

  -?, --help                 Give this help list
      --usage                Give a short usage message
  -V, --version              Print program version

Mandatory or optional arguments to long options are also mandatory or optional
for any corresponding short options.

If neither --interleave or --layer is specified, multiple DEVICEs are
concatenated.

Report bugs to bug-hurd@gnu.org.

The usermux translator - "usermux"

A translator for invoking user-specific translators.

Running "/hurd/usermux --help" gives:

Usage: usermux [OPTION...] [TRANSLATOR [ARG...]]
A translator for invoking user-specific translators

  -C, --clear-patterns       Reset all patterns to empty; this option may then
                             be followed by options to set specific patterns
      --home-pattern=PAT     The string to replace in the translator
                             specification with the user's home directory
                             (default `${home}')
      --uid-pattern=PAT      The string to replace in the translator
                             specification with the uid (default `${uid}')
      --user-pattern=PAT     The string to replace in the translator
                             specification with the user name (default
                             `${user}')
  -?, --help                 Give this help list
      --usage                Give a short usage message

This translator appears like a directory in which user names can be looked up,
and will start TRANSLATOR to service each resulting node.  If no pattern occurs
in the translator specification, the users's home directory is appended to it
instead; TRANSLATOR defaults to /hurd/symlink.

Report bugs to bug-hurd@gnu.org.