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.

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-*.

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).

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.

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.

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.

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.

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)

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.

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_lookupRPC
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.

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.

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.

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.

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.