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, <[email protected]>. 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 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 [email protected].
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 [email protected].
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 [email protected].
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 [email protected].
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 [email protected].
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 [email protected].
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 [email protected].
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 [email protected].
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 [email protected].
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_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 (seelibc/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 [email protected].
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 [email protected].
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 [email protected].
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 [email protected].
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 [email protected].
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 [email protected].
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 [email protected].
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 [email protected].
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 [email protected].