     [file version.texi not included]

Copyright © 1994-2002  Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions.

The GNU Hurd Users Guide
************************

This file documents the usage of GNU Hurd.  This edition of the documentation was last updated for version VERSION of the Hurd.

Introduction
************

The GNU Hurd is the GNU Project's replacement for the Unix kernel. The Hurd is a collection of servers that run on the Mach microkernel to implement file systems, network protocols, file access control, and other features that are normally implemented by the Unix kernel or similar kernels such as Linux.

Audience
========

This manual is designed to be useful to everybody who is interested in using, administering, or programming the Hurd.

If you are an end-user and you are looking for help on running the Hurd, the first few chapters of this manual describe the essential parts of installing, starting up, and shutting down a GNU/Hurd workstation.  Subsequent chapters describe day-to-day use of the system, setting up and using networking, and the use of translators.

If you need help with a specific program, you can get a short explanation of the program's use by typing PROGRAM --help at the command prompt; for example, to get help on GREP, type GREP --help. More complete documentation is available if you type INFO program; continuing with our example of GREP, type INFO grep.

Overview
========

An operating system kernel provides a framework for programs to share a computer's hardware resources securely and efficiently.  This framework includes mechanisms for programs to communicate safely, even if they do not trust one another.

The GNU Hurd breaks up the work of the traditional kernel, and implements it in separate programs.  The Hurd formally defines the communication protocols that each of the servers understands, so that it is possible for different servers to implement the same interface.

The GNU C Library provides a POSIX environment on the Hurd, by translating standard POSIX system calls into interactions with the appropriate Hurd server.

POSIX stands for Portable Operating System Interface.  The term POSIX we hear so much about is a set standards set by the IEEE. Unix like operating systems aim to be compliant or partially compliant. The Hurd is as compliant as any other Unix like operating system. That is why ported applications, implementation of protocols and other essentials services been available since the introduction of the Hurd. But always remember GNU's Not Unix, which is the underlying feature of the Hurd. The Hurd uses POSIX but is growing to address the limitations of Unix-like operating systems.

History
=======

Richard Stallman (RMS) started GNU in 1983, as a project to create a complete free operating system.  In the text of the GNU Manifesto, he mentioned that there is a primitive kernel.  In the first GNUsletter, Feb. 1986, he says that GNU's kernel is TRIX, which was developed at the Massachusetts Institute of Technology.

By December of 1986, the Free Software Foundation (FSF) had ``started working on the changes needed to TRIX'' [Gnusletter, Jan. 1987]. Shortly thereafter, the FSF began ``negotiating with Professor Rashid of Carnegie-Mellon University about working with them on the development of the Mach kernel'' [Gnusletter, June, 1987].  The text implies that the FSF wanted to use someone else's work, rather than have to fix TRIX.

In [Gnusletter, Feb. 1988], RMS was talking about taking Mach and putting the Berkeley Sprite filesystem on top of it, ``after the parts of Berkeley Unix... have been replaced.''

Six months later, the FSF is saying that ``if we can't get Mach, we'll use TRIX or Berkeley's Sprite.''  Here, they present Sprite as a full-kernel option, rather than just a filesystem.

In January, 1990, they say ``we aren't doing any kernel work.  It does not make sense for us to start a kernel project now, when we still hope to use Mach'' [Gnusletter, Jan. 1990].  Nothing significant occurs until 1991, when a more detailed plan is announced:

     ``We are still interested in a multi-process kernel running on top of
     Mach. The CMU lawyers are currently deciding if they can release Mach
     with distribution conditions that will enable us to distribute it. If
     they decide to do so, then we will probably start work. CMU has
     available under the same terms as Mach a single-server partial Unix
     emulator named Poe; it is rather slow and provides minimal
     functionality. We would probably begin by extending Poe to provide full
     functionality. Later we hope to have a modular emulator divided into
     multiple processes.'' [Gnusletter, Jan. 1991].

RMS explains the relationship between the Hurd and Linux in

http://www.gnu.org/software/hurd/hurd-and-linux.html, where he mentions that the FSF started developing the Hurd in 1990.  As of [Gnusletter, Nov. 1991], the Hurd (running on Mach) is GNU's official kernel.

Who Should Use the Hurd?
========================

Firstly, a note for end-users: if you do not consider yourself ``computer literate,'' then you definitely will not want to use the Hurd.  No official release of the Hurd has yet been made, and the system is currently unstable.  If you run the Hurd, you will encounter many bugs. For those people who use their computers for web-surfing, email, word processing, etc., and just want the infernal machine to work, the Hurd's bugs would prove extremely annoying.

For such people, a more stable system is preferable.  Fortunately, the GNU system currently exists in a very stable state with Linux substituted for the Hurd as the kernel, so it is possible for end-users to use a powerful, stable, and Free Unix-like operating system. Debian GNU/Linux, a very high-quality GNU/Linux distribution, is available; in addition, many commercial companies sell boxed GNU/Linux distributions with printed documentation, and, to various extents, take measures to hide the complexity of the system from the user.  Keep in mind that the GNU/Hurd is not the system you use for web-surfing, email, word processing, and other such tasks now ... it is the system that you will use for these tasks in the future.

Those who consider themselves computer literate and are interested in the Hurd, but do not have experience with Unix-like systems may also wish to learn the ropes using a more stable GNU/Linux system.  Unix-like systems are quite different from other systems you may have used, and they take some getting used to.  If you plan to use the Hurd in the future, we recommend you use Debian GNU/Linux.

If you consider yourself computer literate, but are not a programmer, you can still contribute to the Hurd project.  Tasks for non-programmers include running Hurd systems and testing them for bugs, writing documentation, and translating existing documentation into other languages. At present, the majority of the Hurd documentation is availiable only in English and/or French.

Anyone who might be interested in the Hurd, a student studying the system, a programmer helping to develop the Hurd servers, or an end-user finding bugs or writing documentation, will be interested in how the Hurd is similar to, and different from, Unix-like kernels.

For all intents and purposes, the Hurd is a modern Unix-like kernel, like Linux and the BSDs.  The Hurd uses the GNU C Library, whose development closely tracks standards such as ANSI/ISO, BSD, POSIX, Single Unix, SVID, and X/Open.  Hence, most programs available on GNU/Linux and BSD systems will eventually be ported to run on GNU/Hurd systems.

An advantage of all these systems - GNU/Hurd, GNU/Linux, and the BSDs - is that, unlike many popular operating systems, is that they are Free Software. Anybody can use, modify, and redistribute these systems under the terms of the GNU General Public License (see Copying the Hurd) in the case of GNU/Hurd and GNU/Linux, and the BSD license in the case of the BSDs.  In fact, the entire GNU System is a complete Unix-like operating system licensed under the GNU GPL.

Although it is similar to other Free Unix-like kernel projects, the Hurd has the potential to be much more.  Unlike these other projects, the Hurd has an object-oriented structure that allows it to evolve without compromising its design. This structure will help the Hurd undergo major redesign and modifications without having to be entirely rewritten.  This extensibility makes the Hurd an attractive platform for learning how to become a kernel hacker or for implementing new ideas in kernel technology, as every part of the system is designed to be modified and extended.

Scalability has traditionally been very difficult to achieve in Unix-like systems.  Many computer applications in both science and business require support for symmetric multiprocessing (SMP).  At the time of this writing, Linux could scale to a maximum of 8 processors.  By contrast, the Hurd implementation is aggressively multithreaded so that it runs efficiently on both single processors and symmetric multiprocessors. The Hurd interfaces are designed to allow transparent network clusters (collectives), although this feature has not yet been implemented.

Of course, the Hurd (currently) has its limitations.  Many of these limitations are due to GNU Mach, the microkernel on which the Hurd runs. For example, although the Hurd has the potential to be a great platform for SMP, no such multiprocessing is currently possible, since GNU Mach has no support for SMP.  The Hurd has supports less hardware than current versions of Linux, since GNU Mach uses the hardware drivers from version 2.0 of the Linux kernel.  Finally, GNU Mach is a very slow microkernel, and contributes to the overall slowness of systems using the Hurd.

Mach is known as a 1st-generation microkernel - much work has gone into the much-improved 2nd-generation microkernels currently being developed. A long-term goal is to port the Hurd to L4, a very fast 2nd-generation microkernel.  This port will offer substantial imporvements to the system. In the short term, the Hurd developers plan to move the Hurd to OSKit Mach, an improved version of Mach being developed at the University of Utah.

The Hurd is still under active development, and no stable release has been made.  This means that the Hurd's code base is much less mature than that of Linux or the BSDs.  There are bugs in system that are still being found and fixed.  Also, many features, such as a DHCP client, and support for several filesystem types, is currently missing.

The deficiencies in the Hurd are constantly being addressed; for examply, until recently, pthreads (POSIX threads), were missing.  This meant that several major applications, including GNOME, KDE, and Mozilla, could not run on GNU/Hurd.  Now that the Hurd has a preliminary pthreads implementation, we may soon see these applications running on GNU/Hurd systems.

The Hurd is a very modern design.  It is more modern than Linux or the BSDs, because it uses a microkernel instead of a monolithic kernel.  It is also more modern than Apple's Darwin or Microsoft's NT microkernel, since the it has a multi-sever design, as opposed to the single-server design of Darwin and NT. This makes the Hurd an ideal platform for students interested in operating systems, since its design closely matches the recommenations of current operating system theory.  In addition, the Hurd's modular nature makes it much easier to understand than many other kernel projects.

The Hurd is also an excellent system for developers interested in kernel hacking.  Whereas Linux and the BSDs are quite stable, there is still much work to be done on the Hurd; for example, among all the filesystem types in use today, the Hurd only supports ext2fs, ufs, and iso9660fs.  The Hurd offers a developer the opportunity to make a substantial contribution to a system at a relatively-early point in its development.

Hurd Today
==========

The GNU operating system is alive and well today.  In 1998 Marcus Brinkmann brought the Hurd to the Debian Project.  This allowed the Hurd to have a software management system(apt and dpkg), world wide access to the latest free software, and a extreme increase of popularity.

The original architect Thomas Bushnell BSG is involved on the mailing lists helping the young hackers design and help with Hurd development.  There is now a team of individuals from around the world.  They are constantly giving talks at conferences about the importance of design and implementation of the Hurds unique multiserver microkernel enviroment.  There is  also work on porting the Hurd to two other micro-kernels and another architecture.

So far Debian GNU/Hurd has been the most active non-Linux port.  The user applications that are ported to the Hurd are the latest and are actively being improved.  Development of the Hurd within the Debian project has also contributed to incremental development releases on compact-disk.  Also a new developer is allowed to get the source code to the Hurd from anywhere on the planet.  A developer can even get a more recent snapshot release from the the GNU project's alpha.gnu.org (ftp://alpha.gnu.org) server.

Copying
=======

The Hurd is distributed under the terms of the GNU General Public License (see Copying the Hurd).

Installing
**********

Before you can use the Hurd on your favorite machine, you'll need to install all of its software components.  Currently, the Hurd only runs on Intel i386-compatible architectures (such as the Pentium), using the GNU Mach micro-kernel.

If you have unsupported hardware or a different microkernel, you will not be able to run the Hurd until all the required software has been

ported to your architecture.  Porting is an involved process which requires considerable programming skills, and is not recommended for the faint-of-heart.  If you have the talent and desire to do a port, contact bug-hurd@gnu.org in order to coordinate the effort.

Binary Distributions
====================

By far the easiest and best way to install the Hurd is to obtain a Debian GNU/Hurd binary distribution.  Even if you plan on recompiling the Hurd itself, it is best to start off with an already-working GNU system so that you can avoid having to reboot every time you want to test a program.

You can get GNU from a friend under the conditions allowed by the GNU GPL (see Copying the Hurd).  Please consider sending a donation to the Free Software Foundation so that we can continue to improve GNU software.

You can order Debian GNU/Hurd on a CD-ROM from CopyLeft (http://www.copyleft.co.nz/) or you can also FTP the complete GNU system in iso format from your closest GNU mirror,or ftp://ftp.gnu.org/iso.  Again, please consider donating to the Free Software Foundation.

The format of the binary distribution is prone to change, so this manual does not describe the details of how to install GNU.  The README file distributed with the binary distribution gives you complete instructions.

After you follow all the appropriate instructions, you will have a working GNU/Hurd system.  If you have used GNU/Linux (http://www.gnu.org/gnu/linux-and-gnu.html) systems or other Unix-like systems before, the Hurd will look quite familiar.  You should play with it for a while, referring to this manual only when you want to learn more about the Hurd.

If the Hurd is your first introduction to the GNU operating system, then you will need to learn more about GNU in order to be able to use it. This manual will provide the basics for you to expand on and for you to productively use your GNU/Hurd machine.  You should talk to your friends who are familiar with GNU, in order to find out about classes, online tutorials, or books which can help you learn more about GNU.

If you have no friends who are already using GNU, you can find some useful starting points at the GNU web site, http://www.gnu.org/. You can also send e-mail to help-hurd@gnu.org, to contact fellow Hurd users.  You can join this mailing list by sending a request to help-hurd-request@gnu.org.  You may even want to chat with the developers yourself. You can reach some on irc.openprojects.net in the #hurd channel.

Archive Method
==============

Another way to install the Hurd is to use an existing GNU/Linux operating system.  This is the easiest method I have ever seen at installing a working system.   What you need is:

 1. A tarball of a snapshot release.

 2. 1 gb or less of free unpartitioned drive space.

 3. A grub bootdisk.

On your GNU/Linux system you need to make a 1 gb partition with either fdisk or cfdisk.  Then you have to format it for the Hurd. Lets say I made a partition called /dev/hda3 I would format it this way.

     bash-2.05# mke2fs -o hurd /dev/hda3

After this is done you can mount the partition and extract your archived snapshot into that directory.

     bash-2.05# mount /dev/hda3 /mnt
     bash-2.05# cd /mnt
     bash-2.05# tar zxvpf ~/gnu-latest.tar.gz

After your done you should be able to reboot.  The grub boot disk is needed to boot the Hurd.  Once your booted you can finish the installation by running the native-install file.  I have to note that when you are booting the Hurd for the first time you must give Grub the single-user option (-s) like in the following example.   Also note that the first long module entry is all on one line.

     title GNU/Hurd
     root (hd0,0)
     kernel /boot/gnumach.gz -s root=device:hd0s1
     module /hurd/ext2fs.static --multiboot-command-line=${kernel-command-line} --host-priv-port=${host-port} --device-master-port=${device-port} --exec-server-task=${exec-task} -T typed ${root} $(task-create) $(task-resume)
     module /lib/ld.so.1 /hurd/exec $(exec-task=task-create)

Cross-Compiling
===============

Another way to install the Hurd is to use an existing operating system in order to compile all the required Hurd components from source code. This is called cross-compiling, because it is done between two different platforms.

This process is not recommended unless you are porting the Hurd to a new platform.  Cross-compiling the Hurd to a platform which already has a binary distribution is a tremendous waste of time... it is frequently necessary to repeat steps over and over again, and you are not even guaranteed to get a working system.  Please, obtain a GNU binary distribution (see Binary Distributions), and use your time to do more useful things.  If you are capable of cross-compiling, then you are definitely skilled enough to make more useful (and creative) modifications to the GNU system.

To emphasize this point: downloading the entire GNU system over a 9600 baud modem takes much less time than cross-compilation, and provides better results, too.

If you are still sure that you would like to cross-compile the Hurd, you should send e-mail to the bug-hurd@gnu.org mailing list in order to coordinate your efforts.  People on that list will give you advice on what to look out for, as well as helping you figure out a way that your cross-compilation can benefit Hurd development.  After that, don your bug-resistant suit, and read the INSTALL-cross file, which comes with the latest Hurd source code distribution.  The instructions in INSTALL-cross are usually out-of-date, but they contain some useful hints buried amongst the errors.

Bootstrap
*********

Bootstrapping (The term bootstrapping refers to a Dutch legend about a boy who was able to fly by pulling himself up by his bootstraps.  In computers, this term refers to any process where a simple system activates a more complicated system.) is the procedure by which your machine loads the microkernel and transfers control to the Hurd servers.

Bootloader
==========

The bootloader is the first software that runs on your machine. Many hardware architectures have a very simple startup routine which reads a very simple bootloader from the beginning of the internal hard disk, then transfers control to it.  Other architectures have startup routines which are able to understand more of the contents of the hard disk, and directly start a more advanced bootloader.

Currently, GRUB (The GRand Unified Bootloader, available from http://www.gnu.org/software/grub/.) is the GNU bootloader. GNU GRUB provides advanced functionality, and is capable of loading several different kernels (such as Linux, DOS, and the *BSD family).

>From the standpoint of the Hurd, the bootloader is just a mechanism to get the microkernel running and transfer control to the Hurd servers. You will need to refer to your bootloader and microkernel documentation for more information about the details of this process.

Installing Grub
===============

At the moment your are booting the Hurd with a floppy disk.  This is not a good idea to do regularly because of the unreliability of the floppy disk.  This section will show you how to install GRUB into the master boot record of your hard-disk. What you need are:

 1. Grub boot floppy.

 2. Grub installed onto Hard-disk.

 3. Knowledge of where you installed GNU/Hurd.

First you will need to make a directory for grub.  Do this now(You must be logged in as root).

     bash-2.05#mkdir /boot/grub

Now you must copy the contents of the grub installed loader files.  These are usually located in /lib/grub/i386-unknown-pc/.  All the files in this directory need to be copied to the boot directory.

     bash-2.05#cp /lib/grub/i386-unknown-pc/* /boot/grub/

Now you have two more things to do.  Next you have to construct a menu.lst file to put in your /boot/grub directory.  This file is the file that displays a menu at boot time.  Before you tackle this you should read the grub info pages to get a better understanding of the way grub works. The reason I ask this of you is that the Hurd is constantly being worked on to boot more effiecently and the syntax may change with the Hurd's development releases.

This is my sample menu.lst file

     timeout  10

     color light-grey/black red/light-grey

     title Debian GNU/Hurd
     root (hd0,0)
     kernel /boot/gnumach.gz root=device:hd0s1
     module /hurd/ext2fs.static --multiboot-command-line=${kernel-command-line} --host-priv-port=${host-port} --device-master-port=${device-port} --exec-server-task=${exec-task} -T typed ${root} $(task-create) $(task-resume)
     module /lib/ld.so.1 /hurd/exec $(exec-task=task-create)

     title Debian GNU/Linux
     root (hd0,1)
     kernel /vmlinuz root=/dev/hda2 ro

Now that you have your menu.lst file in /boot/grub you are ready to install the grub and make your machine bootable from the hard-disk.  You should write down what you wrote in your menu.lst file.  You need this information to type into the grub command line.  If you forget your grub boot floppy should be able to boot your system so you can write that data down and continue with the installation of grub.

When you get to your boot menu of the floppy press C.  The C will put you at the Grub command prompt.  You need to start with the root command.

     :grub>root (hd0,0)

My GNU/Hurd is installed on the first partition of the first drive.  Thats what the above example is telling Grub.  After you press enter it should print out something along the lines as <ext2 and a bunch of numbers>.  This means it found your filesytem that wants to be the root. Next you need Grub to load the kernel.  This is the tricky part.  Heres what I have.

     :grub>kernel /boot/gnumach.gz root=device:hd0s1

Once you press enter again you'll see some more info.  If you get an error that just means you either typed wrong or you picked the wrong root device for Grub.

Next you need to enter the modules for Grub to use. This is probably the trickiest part of booting the rest of the Hurd.

     :grub>module /hurd/ext2fs.static --multiboot-command-line=${kernel-command-line} --host-priv-port=${host-port} --device-master-port=${device-port} --exec-server-task=${exec-task} -T typed ${root} $(task-create) $(task-resume)

Note this should be all on one line no <enter> until the end.

     :grub>module /lib/ld.so.1 /hurd/exec $(exec-task=task-create)

To fully understand these two module commands you can check the Hurd Reference Manual.  That manual should explain every detail. These are very important for developers they can do many things with the Grub bootloader and the Hurd.

As soon as you start updating your system(rebuilding kernels,Hurd servers) the Grub menus will get more complex.  After this command if your still with me (if not read the Grub docs)you can safely install with.

     :grub>setup (hd0)

If this is successful you should be able to press the reset button and remove the Grub floppy.  You just installed Grub to the master boot record of the hard disk this alone is something many men and women dare not tread.

Server Bootstrap
================

The serverboot program has been deprecated.  Newer kernels support processing the bootscript parameters and boot the Hurd directly.

The serverboot program is responsible for loading and executing the rest of the Hurd servers.  Rather than containing specific instructions for starting the Hurd, it follows general steps given in a user-supplied boot script.

To boot the Hurd using serverboot, the microkernel must start serverboot as its first task, and pass it appropriate arguments. serverboot has a counterpart, called boot, which can be invoked while the Hurd is already running, and allows users to start their own complete sub-Hurds (see The Sub-Hurd).

Invoking serverboot
-------------------

The serverboot program has the following synopsis:

     serverboot -SWITCH... [[HOST-PORT DEVICE-PORT] ROOT-NAME]

Each SWITCH is a single character, out of the following set:

a
     Prompt the user for the ROOT-NAME, even if it was already supplied on the command line.

d
     Prompt the user to strike a key after the boot script has been read.

q
     Prompt the user for the name of the boot script.  By default, use ROOT-NAME:/boot/servers.boot.

All the SWITCHES are put into the ${boot-args} script variable. HOST-PORT and DEVICE-PORT are integers which represent the microkernel host and device ports, respectively (and are used to initialize the ${host-port} and ${device-port} boot script variables).  If these ports are not specified, then serverboot assumes that the Hurd is already running, and fetches the current ports from the procserver (FIXME xref).

ROOT-NAME is the name of the microkernel device that should be used as the Hurd bootstrap filesystem.  serverboot uses this name to locate the boot script (described above), and to initialize the ${root-device} script variable.

Boot Scripts
------------

Boot Scripts are used to boot further Hurd systems in parallel to the first, and are parsed by serverboot to boot the Hurd.  See /boot/servers.boot for an example of a Hurd boot script.

The Sub-Hurd
------------

The boot program can be used to start a set of core Hurd servers while another Hurd is already running.  You will rarely need to do this, and it requires superuser privileges to control the new Hurd (or allow it to access certain devices), but it is interesting to note that it can be done.

Usually, you would make changes to only one server, and simply tell your programs to use it in order to test out your changes.  This process can be applied even to the core servers.  However, some changes have far-reaching effects, and so it is nice to be able to test those effects without having to reboot the machine.

Here are the steps you can follow to test out a new set of servers:

 1. Create a pseudo-root device.  Usually, you would do this by creating a new partition under your old Hurd, and initializing it with your favorite filesystem format.  boot understands the regular libstore options (FIXME xref), so you may use a file or other store instead of a partition.

          $ dd if=/dev/zero of=my-partition bs=1024k count=400
          400+0 records in
          400+0 records out
          $ mke2fs ./my-partition
          mke2fs 1.18, 11-Nov-1999 for EXT2 FS 0.5b, 95/08/09
          my-partition is not a block special device.
          Proceed anyway? (y,n) y
          Filesystem label=
          OS type: GNU/Hurd
          Block size=1024 (log=0)
          Fragment size=1024 (log=0)
          102400 inodes, 409600 blocks
          20480 blocks (5.00%) reserved for the super user
          First data block=1
          50 block groups
          8192 blocks per group, 8192 fragments per group
          2048 inodes per group
          Superblock backups stored on blocks:
                  8193, 24577, 40961, 57345, 73729, 204801, 221185, 401409
          Writing inode tables: done
          Writing superblocks and filesystem accounting information: done
          $

 2. Copy the core servers, C library, your modified programs, and anything else you need onto the pseudo-root.

          $ settrans -c ./my-root /hurd/ext2fs -r `pwd`/my-partition
          $ fsysopts ./my-root --writable
          $ cd my-root
          $ tar -zxpf /pub/debian/FIXME/gnu-20000929.tar.gz
          $ cd ..
          $ fsysopts ./my-root --readonly
          $

 3. Create a new boot script (FIXME xref).

 4. Run boot.

          -$ boot -D ./my-boot ./my-boot/boot/servers.boot ./my-partition
          [...]

 5. Here is an example using a hard drive that already has a GNU/Hurd system installed on an ext2 filesystem on /dev/hd2s1.

          $ settrans /mnt /hurd/ex2fs --readonly /dev/hd2s1
          $ boot -d -D /mnt -I /mnt/boot/servers.boot /dev/hd2s1

 6. See Invoking boot for help with boot.

Note that it is impossible to share microkernel devices between the two running Hurds, so don't get confused with which one your testing.  When you're finished testing your new Hurd, then you can run the halt or reboot programs to return control to the parent Hurd.

If you're satisfied with your new Hurd, you can arrange for your bootloader to start it, and reboot your machine.  Then, you'll be in a safe place to overwrite your old Hurd with the new one, and reboot back to your old configuration (with the new Hurd servers).

Invoking boot
-------------

Usage: boot [OPTION...] BOOT-SCRIPT DEVICE...

--kernel-command-line=COMMAND LINE
-c
     Simulated multiboot command line to supply.

--pause
-d
     Pause for user confirmation at various times during booting.

--boot-root=DIR
-D
     Root of a directory tree in which to find the files specified in BOOT-SCRIPT.

--interleave=BLOCKS
     Interleave in runs of length BLOCKS.

--isig
-I
     Do not disable terminal signals, so you can suspend and interrupt the boot program itself, rather than the programs running in the booted system.

--layer
-L
     Layer multiple devices for redundancy.

--single-user
-s
     Boot into single user mode.

--store-type=TYPE
-T
     Each DEVICE names a store of type TYPE.

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.

Shutdown
========

You can shut down or reboot your hurd machine by typing these commands.

     bash-2.05# reboot <ENTER>

     bash-2.05# halt <ENTER>

In a matter of seconds it should tell you that it is in a type loop and pressing control, alt, and delete at the same time will make the Hurd reboot.  It is now safe to shut the computer off.

Using
*****

Now that you have the Hurd installed and booting you're probably wondering "What can I do with it?".  Well the Hurd is capable of being a console based workstation.  The X Window System is known to work but is not require to learn the Hurd.  What this chapter is for is to get the user acquainted to the command line of the Hurd.  You should read the Hurd's FAQ and also have a working knowledge of the shell.  If not you can read The Basics for a brief intro of whats needed.

The Basics
==========

Note: When showing command prompts, I use # to indicate root user, and $ to indicate normal user.

If you successfully installed the Hurd and you are in multi-user mode you should have a login shell ready for you it should look like this.

     GNU 0.3 (hurd)

     Most of the programs included with the Debian GNU/Hurd system are
     freely redistributable; the exact distribution terms for each program
     are described in the individual files in /usr/share/doc/*/copyright

     Debian GNU/Hurd comes with ABSOLUTELY NO WARRANTY, to the extent
     permitted by applicable law.
     login>

     Type Login:USER or type HELP

You can go ahead and type login root<ENTER> to get started.

What you need to know for using the Hurd is your basic Unix-like commands. The GNU Project has written a replacement for almost every Unix command. You need to learn how to copy,move,view,and modify files.  It also is important to learn one of the many editors that are available for the Hurd. The default editor is Nano which is very simple and self explanatory yet not as powerful as Emacs or Vi.  It is there because it's small in size and easy on the memory of your computer.  I am not going to cover it here because it is quite self explanatory.  This section hopes to get you started with these necessity commands.  If you have knowledge of these already you can probably skip ahead.  Also you might want to get comfortable with the default editor first then come back to this section to learn your basic GNU/Hurd shell commands.

The shell is the the program that interacts with the file system and the data on the file system.  This is called bash(Bourne again shell).  Once you get comfortable with the shell you can happily sit at any Unix-Like workstation and get some work done.  It is very important that you get comfortable with the shell.  It is also called terminal,console, etc.  At this prompt you should be ready to begin.  (Note:Shell variables cause your prompt to display your current working directory.  Your prompt may look like this "user@hurd:~/$".)

     bash-2.05$

To make a directory for your self you would use the mkdir(make directory) command.  You can make as many as you want as long as they are in your home directory.

     bash-2.05$ mkdir docs tmp sources <ENTER>

To change directories you would use the cd(change directory) command.  One thing to remember is when your anywhere in the filesytem the cd command alone will put you back in your home directory.  (Note:The bash shell features command line completion, by pressing the first letter of the file or directory plus<TAB> will do this.)

     bash-2.05$ cd /usr/local <ENTER> #this puts you in the /usr/local directory.
     bash-2.05$ cd <ENTER>            #this puts you back in the home directory.

There is another short cut,  cd ../ This puts you in the directory above the one your in.

To view a file there are many ways, but we'll use the most common command called cat.

     bash-2.05$ cat README | less <ENTER>

"What is that extra stuff you typed?"  See we need the | (pipe symbol) to take the output of README and feed it to the less command.  Less allows you to view the documents one screen at a time and it allows you to go back to the beginning of the document.  You have to type Q to get out of less.

To copy a file from one place to another you use the cp(copy) command.  The cp command has many options such as cp -f -v -r.  Luckily for us the info command will clarify many of the confusing commands and all there options.

     bash-2.05$ cp README chapter1.txt foo1/ <ENTER>

What we did is copy two files to the foo1 directory.  Here are a few good options to remember.

     bash-2.05$ cp -rfv foo1/ file2.txt tmp/ <ENTER>
     bash-2.05$ cp -rf /cdrom/* ~/ <ENTER>

The -r means recursive so anything in the foo1 directory gets copied including file2.txt to tmp.  The -f means force I have a habit of forcing things. The -v means verbose, It will show you on the screen what files are being copied.  In the second example we have this ~/ this is a short cut meaning your home directory.  So that command would copy the contents of /cdrom to your home directory.(Note:The asterik symbol '*' is called a wildcard character which means "anything".)

To rename or move a file or directory you would use the mv(move) command. Be careful because mv is a very powerful command.  You can lose data if your not careful about what you do.  To rename a file or directory you would use.

     bash-2.05$ mv foo1/ foo2 <ENTER>

Now you no longer have a foo1 directory, it's called foo2 now.  The same thing can be done with plain files too.

I bet your saying "I'm doing all this work but how do I view my directories?" You answer would be the ls(list)command.  The ls command is another command with many options.

     bash-2.05$ ls -al <ENTER>

The two options I have here are the most used that I can think of.  The -a will show us the hidden files in the current directory.  The -l option tells us to display the directory in long format.  This means it shows us the date modified, file size, file attributes etc.  Like I was saying in the beginning a grasp of these basics will help you on any Unix-like operating system.

Now that you have made all this mess in your home directory I bet your wondering how you can get rid of things.  There are two important deleting commands.  The rm(remove)command is convienent for removing files.The rm command can also remove directorys that the rmdir command can't, first I'll show the basic rm example then my favorite with the extra options.  The rmdir command will only delete directories that are empty.

     bash-2.05$ rm README <ENTER>

Now rm with some options.

     bash-2.05$ rm -rf foo2/ file1.txt <ENTER>

The second example is very powerful.  The -r means recursive and the -f means force.  This removes all the contents of foo2 including the file1.txt.

These are only the basic commands to get you started there are many,many two and three letter commands.  The more you use the Hurd the more options and commands you'll learn.  The more you learn the more freedom you'll have and that is a very valuable thing to have.

Now that you have been cruising around you file system you might be wondering how much space you have left on your drive.  There is a simple command to check.

     bash-2.05$ df / <ENTER>
     Filesystem           1k-blocks      Used Available Use% Mounted on
     /dev/hd0s1            1920748   1203996    619180  67% /

If you don't put a directory after the command such as / or /home the df(diskfree) command will spit out some errors.

If your prompt is not telling you what directory your in you can use the pwd (present working directory)command.

     bash-2.05$ pwd <ENTER>
     /usr/src

Always remember info is your friend on the Hurd.

More Basics
===========

In this section I want the user to learn some extra things to make life interesting.  You will need to learn about archives.  Archives come in many different formats.  Archive is a general term for software packages. You may have heard of a tarball, this is a form of a archive.  The file extensions tell us what it is.  Generally they come in forms of .tgz, .tar.gz, .tar.bz2, .gz, etc.

This is a method of taking files packaging them and compressing them.  It has been around for ever.  Most software that you try and install from source-code will be packaged this way.  I will try and give you some examples and if your confused always consult the info pages.

Lets say we get a tar file that has some documents you want to read.  Make sure your in your home directory when you try.

     bash-2.05$ tar xv docs.tar <ENTER>

After running this command you would see the contents of the tar file extracted to your home directory.  The x stands for extract and v means verbose which shows us the contents of the archive as it's being decompressed.  Compressing a file or directory is very simliar.  You would use this.

     bash-2.05$ tar -cv new.tar foo1/ foo2/ <ENTER>

The -c is to create the tar file.  We add the name of the tar file then the contents we want.  In the previous example we created a file called new.tar and we added the directories foo1/ and foo2/ to the tar file.  With the -v option we see what is being added.

The next most common archive file is the gzip format.  Files with .gz are associated with gzip.  These utlities work so well together that people have patched the tar command so that it can compress and decompress gzip files.  If your file has no .tar in the file name and only .gz at the end you cannot use tar.

     bash-2.05$ tar -zxv file.tar.gz <ENTER> #This file was compressed once with tar
                                              then with gzip
     bash-2.05$ gzip -d file.gz <ENTER>     #notice no tar in filename means you use
                                              gzip

In the first example the z after the tar command is the option that tells tar that the file has gzip involved with it.  The x and the v were used already so we know what they are used for.  The second example is the gzip command it uses the d option to decompress the gzip archive.  A command that is linked to gzip is called gunzip.  This is the same as gzip -d but it is used because you don't have to remember any options.

     bash-2.05$ gunzip file.gz <ENTER>

To compress tar files or any file using gzip you would use this:

     bash-2.05$ gzip -9 file.tar <ENTER>

The -9 means best compression.  There are many options available for gzip. A quick browse through the info pages will tell you everything you need.

Another common archiving example is the bzip2 format. The bzip2 format is usually seen as .tar.bz2.  This format is known to be one of the best compression utilities.  To extract a bzip2 file you would use.

     bash-2.05$ bunzip2 file.bz2 <ENTER>

Like the gzip format the bzip2 format has many options.  You will probably see bzip2 compressing tar files.  The bzip2 utility actually has a lot of other commands linked to it.  To extract a file thats been compressed with tar and bzip2 you would use the following example.

     bash-2.05$ bzcat file.tar.bz2 |tar -xv <ENTER>

The bzcat command is a combination of bunzip2 and cat.  We bzcat the file then pipe(|)the file to the tar command.  Once again I use -x to extract the file and -v to see it's contents.  To compress a file using bzip2 you would use:

     bash-2.05$ bzip2 -z file1.txt <ENTER>

This command makes file1.txt end up looking like file1.txt.bz2 and slightly smaller.  You can also use the '-9' option for best compression.

Hopefully this little chapter has gotten you more interested in using the Hurd. If you are still confused please read the info pages for the command your confused on.  The command info will give you a list of all the programs on your Hurd machine that have documentation with them.  The best way to learn GNU utilities is to read and practice.  The Hurd is just like music, you can never learn enough. This chapter is meant to give you a stepping stone to freedom.

Administration
==============

After the last chapter you probably wondering about this root user that everyone is so fond of.  The Hurd is trying to get all things root out of the picture and allow you the freedom of doing things only root can do on lagacy Unix systems.  The designers and developers want you the user to be able to do things that you can't on a traditional Unix-like operating system. For the time being you will have to deal with the root user.  One reasonable request of the Unix type gurus is making a normal user (unpriveledged to write anywhere on the filesystem besides the user's home directory).  The reasoning behind this is that you a normal user can not mess up your computer.  This is a decent compromise because the more we explore and play the more likely we'll lose a important file or do something stupid.  So what we'll do is set up a user account for you.  You have to be root to do this.

     bash-2.05# adduser <ENTER>

That's it!  The computer will prompt you for a user-name and password then you can just answer yes or whatever you require to the rest of the requests. To change the password on your account you just created you would type.

     bash-2.05# passwd <USER_NAME> <ENTER>
     Please Enter a Password:

There is a command that helps you become root from a normal user account. This command is called su.  When you type su you are required to enter a password (if you have one) for the root.  This command works the other way also for instance if a ssh(Secure Shell) server doesn't allow root you can su to a user that has an account on that server.

     bash-2.05$ su <ENTER>
     password:

There are a lot of commands related to the Administering unix-like operating systems.  As a normal user a lot is unneeded.  Making a new user and giving him/her a password is enough for now.  If you are interested in becoming a Administrator there are plenty of books and classes out there.

Accessing the cdrom
===================

On the Hurd we don't mount anything.  Mount is a Unix command.  The Hurd has a similar mechanism to accessing devices called "setting a translator".  We use the settrans command to do this.  Settrans is a program that aligns a Hurd Server(or translator) to a device supported by the kernel.  For instance on my GNU/Hurd system my cdrom device was detected as hd2.  To get to my data on a iso9660 cdrom I first had to make the device.  Then I had to run the settrans command.  This had to be done as the root user(root is the only user that has these privileges).

     bash-2.05# cd /dev
     bash-2.05# ./MAKEDEV hd2
     bash-2.05# settrans -ac /cdrom /hurd/isofs /dev/hd2

This isn't too hard is it?  Those options after settrans are very important. The -a makes the /hurd/isofs translator active.the -c creates the translator. The -c is only needed the first time.

Now you can cd /cdrom and see your data on the cdrom.

Accessing the floppy
====================

This section will help you get some data off of your floppy disk.I note that the vfat(fat32) and msdos(fat16)file systems or currently not supported. The support will come eventually but for now you can only access GNU/Linux floppys. Remeber that you must be root to get to your floppy.

     joe@hurd# settrans -a /floppy /hurd/ext2fs /dev/fd0

Now you can head to the /floppy directory and see your data.

Networking
**********

In this chapter we'll teach the Hurd's networking features.  The Hurd has some basic networking functions.  The Hurd's networking is a work in progress.  The services that the Hurd has now should be sufficient for the average user.  Available now are ftp,nfs,telnet, surfing the web, and reading e-mail.

Configuring
===========

Before we get to the outside world we need to configure the network card. This is done with the settrans command yet it can be a little tricky.  First you have to pay attention when you boot to see if the microkernel detected you card as eth0.  Once your sure you network card has been detected you can give it the translator that it needs.

     bash-2.05# settrans -fgcap /servers/socket/2 /hurd/pfinet -i eth0 \
     -a 192.168.1.3 -m 255.255.255.0 -g 192.168.1.5 <ENTER>

In this example the settrans command uses the following options 'f', 'g', 'c', 'a', and 'p' which I'll explain.  The -fg forces anything that is attached to /server/socket/2 and /hurd/pfinet to go away.  Next the -c tells settrans to create a translator.  The -ap tells the /server/socket/2 and /hurd/pfinet to be both active and passive. These passive option will make the configuration stick even after the reboots and shutdowns.  Here are the rest of the options.

     -i eth0 = The interface that we are configuring.
     -a 192.168.1.3 = This is the ip address of my machine.
     -m 255.255.255.0 = This is the netmask of my machine.
     -g 192.168.1.5 = This is the gateway machine on the network.

Unfortunately, the Hurd currently has no DHCP client (DHCP stands for Dynamic Host Configuration Protocol, its used by many computers to attach themselves to a network). There is, however, a workaround if you have another operating system, such as Debian GNU/Linux, installed on your Hurd box. In describing this workaround, I'll assume that you are using a GNU/Linux system.

Boot GNU/Linux and log in as root. Type:

     # ifconfig
     eth0      Link encap:Ethernet  HWaddr 00:E0:4C:E1:C0:6D
               inet addr:154.17.21.134  Bcast:154.17.31.255  Mask:255.255.240.0
               UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
               RX packets:16187 errors:0 dropped:0 overruns:0 frame:0
               TX packets:438 errors:0 dropped:0 overruns:0 carrier:0
               collisions:0 txqueuelen:100
               RX bytes:2235054 (2.1 MiB)  TX bytes:59122 (57.7 KiB)
               Interrupt:11 Base address:0xe400

     lo        Link encap:Local Loopback
               inet addr:127.0.0.1  Mask:255.0.0.0
               UP LOOPBACK RUNNING  MTU:3924  Metric:1
               RX packets:366 errors:0 dropped:0 overruns:0 frame:0
               TX packets:366 errors:0 dropped:0 overruns:0 carrier:0
               collisions:0 txqueuelen:0
               RX bytes:18916 (18.4 KiB)  TX bytes:18916 (18.4 KiB)

     # route
     Kernel IP routing table
     Destination     Gateway         Genmask         Flags Metric Ref    Use Iface
     154.17.16.0     *               255.255.240.0   U     0      0        0 eth0
     default         MYrouter.Domain 0.0.0.0         UG    0      0        0 eth0

Note the inet addr and Mask from ifconfig, and the Destination field from route. In our example, these values are 154.17.21.134, 255.255.240.0, and 154.17.16.0, respectively. These are your ip address, netmask, and gateway machine addresses. Reboot into the Hurd, and use these values to set your network translator as described above.

The next items to configure are our resolv.conf file and our hosts file. These are located in the /etc directory.  All of GNU/Hurd's configuration files are located in the /etc directory.  The resolv.conf file is the first file to edit.  It only consists of 2 to 3 lines but it is one of the most important files that gets you online.  Here is an example

     search mydomain            #This should be your networks domain name
     nameserver xxx.xxx.xxx.xxx #These should be the primary and secondary
     nameserver xxx.xxx.xxx.xxx #ip addresses of your isp's nameservers(aka DNS servers)

If you used the DHCP workaround described above, just copy your /etc/resolv.conf (in GNU/Linux) to /etc/resolv.conf (in GNU/Hurd).

After this is all set up you should be able to ping any host on the Internet and recieve a response.The next file to setup is the /etc/hosts file.  This file is used for machines you access frequently.  Instead if typing ip addresses for computers on your network you edit /etc/hosts to allow you to just type the name of the computer you want to access.

     127.0.0.1      hurd localhost
     192.168.1.3    hurd.mydomain.org hurd
     192.168.1.5    jojo.mydomain.org jojo
     192.168.1.6    mojo.mydomain.org mojo

Now I can access 192.168.1.5 by simply using its name jojo.  The same is true with mojo also. For instance if I wanted to telnet into one of those machines I would type telnet jojo(With the proliferation of mischief on the Internet it is recommended you use the OpenSSH suite to access remote computers).

Accessing FTP
=============

FTP stands for File Transfer Protocol.  This protocol has been around since the beginnings of GNU and Unix.  It is a easy and fast way of sending files to friends, family, and colleagues.  The Hurd has two methods of using ftp. One is setting a translator with the Hurds ftpfs server.  The other way is the traditional client server method where you login and use get and put commands.

The ftpfs translator is quite unique.  It allows the user to have a remote ftp server accessible on a local directory.  You the user would then begin copying files like it was just another directory.

     $bash-2.05#settrans -ac /mnt /hurd/ftpfs / alpha.gnu.org

This command will set a translator for ftpfs.  What happens is the ftpfs translator places the root directory of alpha.gnu.org's anonymous ftp server on the /mnt directory. Now one can access the data like is was a local filesystem.

In the traditional matter the FTP protocol is accessed using a client. Typical console based clients are the ones that come with the inet-utils package (The Hurds native ftp client,ncftp, and many others).  The traditional method of ftp is pretty much a standard for Unix-like operating systems. If you learn this method you should be able to comfortably sit at any Unix-like workstation and send and retrieve files. I will give you a start but their are many more options so read the info pages for some more complex operations.

     bash-2.05:$ftp <ENTER>
     ftp>open ftp.gnu.org

You should then be prompted for a user-name and password.  You can login to servers on the Internet who offer anonymous ftp access.  A anonymous ftp server is a server that allows anyone access to it's files.  You would simply type anonymous at the user prompt then type your e-mail address as the password.

The standard commands that are used are get, put, mget, mput, ls, pwd, and cd.  These will work with any standard ftp client.  The commands themselves are self explanatory.  The mget and mput are for multiple files.  An example would be.

     ftp> mget *.tar.gz

This would try to download any files in the current directory with a .tar.gz extensions.  Don't worry if you say mget instead of get by accident because it will prompt you at every file.  It will allow you to say yes, no, all, abort and quit.  The ftp protocol and applications are fairly simple to pick up, you just have to practice.  Trying it a handful of times will get you very familiar, quickly.

Acessing NFS
============

The NFS protocol is a standard method for sharing files between Unix-like workstations.  The server allocates directories that it wants sharable through exporting.  Traditionally the workstation would mount the shared directory onto the local file system.

For instance, Server1's /etc/exports file it says:

/usr/src           mojo(rw,insecure)

This would allow the workstation known as mojo read and write access to the /usr/src directory.  The workstation would then type mount Server1:/usr/src /mnt.  The workstation(mojo) can ls /mnt and see all the files in Server1's /usr/src directory.  (Note: The /etc/hosts file on both server and workstation should have appropriate ip address' for things to work.)

On the Hurd we access a network share by setting the nfs translator.  This is done like this:

     bash-2.05# settrans -ac /mnt /hurd/nfs hostname:/shared/directory

What happens is the remote shared directory is visible on our /mnt directory. We can then start copying,reading, and writing files like they were our own. This is just the basics of the NFS protocol.  If you are very interested in NFS there is limitless amounts of documentation on the Internet.  It is well known to be insecure so be very careful with what your doing.

Web Surfing
===========

On the Hurd we can surf the web on the console.  The program that we use is called Lynx. Lynx is a text mode web browser.  The benefits of using a text mode web browser is speed and simplicity.  In text mode you don't have to load any graphics.  You also don't get those annoying pop-ups and other annoyances that are involved with the World Wide Web.  To use lynx you type the command lynxthen a URL like this example.

     bash-2.05$ lynx www.google.com <ENTER>

This starts us out with google.com.  To go to another URL you type the letter 'g' meaning Go.  Lynx then prompts you for a address to go to. Accessing links on a web page you would press the 'Right' button.  To go back you would press the 'Left' button.  To get help with lynx pressing the 'h' button gives us a big section of help topics.  You can even download information by placing the cursor over the item you want and pressing the 'p' button.  Lynx then prompts us to "Save to File" or "Print".  Lynx is very addictive and once you get used to it you might not want anything else.

Translators
***********

The Hurd filesystem allows you to set translators on any file or directory that you own.  A translator is any Hurd server which provides the basic filesystem interface.  Translated nodes are somewhat like a cross between Unix symbolic links and mount points.

Whenever a program tries to access the contents of a translated node, the filesystem server redirects the request to the appropriate translator (starting it if necessary).  Then, the new translator services the client's request.  The GNU C library makes this behavior seamless from the client's perspective, so that standard Unix programs behave correctly under the Hurd.

Translators run with the privileges of the translated node's owner, so they cannot be used to compromise the security of the system.  This also means that any user can write their own translators, and provide other users with arbitrary filesystem-structured data, regardless of the data's actual source. Other chapters in this manual describe existing translators, and how you can modify them or write your own.

The standard Hurd filesystem servers are constantly evolving to provide innovative features that users want.  Here are a few examples of existing translators:

  * Disk-based filesystem formats, such as ext2fs, ufs, and isofs.

  * Network filesystems, such as nfs and ftpfs.

  * Single files with dynamic content, such as FIXME: we need a good example.

  * Hurd servers which translate rendezvous filesystem nodes in standard locations, so that other programs can easily find them and use server-specific interfaces.  For example, pflocal implements the filesystem interfaces, but it also provides a special Unix-domain socket RPC interface (FIXME xref).  Programs can fetch a port to this translator simply by calling file_name_lookup (FIXME xref) on /servers/socket/1 (The number 1 corresponds to the PF_LOCAL C library socket domain constant.), then use Unix socket-specific RPCs on that port, rather than adhering to the file protocol.

This section focuses on the generic programs that you need to understand in order to use existing translators.  Many other parts of this manual describe how you can write your own translators.

Invoking settrans
=================

The settrans program allows you to set a translator on a file or directory.  By default, the passive translator is set (see the --passive option).

The settrans program has the following synopsis:

     settrans [OPTION]... NODE [TRANSLATOR ARG...]

where TRANSLATOR is the absolute filename of the new translator program.  Each ARG is passed to TRANSLATOR when it starts. If TRANSLATOR is not specified, then settrans clears the existing translator rather than setting a new one.

settrans accepts the following options:

-a
--active
     Set NODE's active translator.  Active translators are started immediately and are not persistent: if the system is rebooted then they are lost.

-c
--create
     Create NODE as a zero-length file if it doesn't already exist.

-L
--dereference
     If NODE is already translated, stack the new translator on top of it (rather than replacing the existing translator).

--help
     Display a brief usage message, then exit.

-p
--passive
     Set NODE's passive translator.  Passive translators are only activated by the underlying filesystem when clients try to use the NODE, and they shut down automatically after they are no longer active in order to conserve system resources.

     Passive translators are stored on the underlying filesystem media, and so they persist between system reboots.  Not all filesystems support passive translators, due to limitations in their underlying media. Consult the filesystem-specific documentation to see if they are supported.

     If you are setting the passive translator, and NODE already has an active translator, then the following options apply:

     -g
     --goaway
          Tell the active translator to go away.  In this case, the following additional options apply:

          -f
          --force
               If the active translator doesn't go away, then force it.

          -S
          --nosync
               Don't flush its contents to disk before terminating.

          -R
          --recursive
               Shut down all of the active translator's children, too.

     -k
     --keep-active
          Leave the existing active translator running.  The new translator will not be started unless the active translator has stopped.

-P
--pause
     When starting an active translator, prompt and wait for a newline on standard input before completing the startup handshake.  This is useful when debugging a translator, as it gives you time to start the debugger.

-t SEC
--timeout=SEC
     If the translator does not start up in SEC seconds (the default is 60), then return an error; if SEC is 0, then never timeout.

--version
     Output program version information and exit.

-x
--exclusive
     Only set the translator if there is none already.

Invoking showtrans
==================

The showtrans program allows you to show the passive translator setting on a file system node.

The showtrans program has the following synopsis:

     showtrans [OPTION]... FILE...

showtrans accepts the following options:

-p
--prefix
     Always display FILENAME: before translators.

-P
--no-prefix
     Never display FILENAME: before translators.

-s
--silent
     No output; useful when checking error status.

-t
--translated
     Only display files that have translators.

Invoking mount
==============

Invoking fsysopts
=================

The fsysopts program allows you to retrieve or set command line options for running translator FILESYS.

The fsysopts program has the following synopsis:

     fsysopts [OPTION...] FILESYS [FS_OPTION...]

fsysopts accepts the following options:

-L
--dereference
     If FILESYS is a symbolic link, follow it.

-R
--recursive
     Pass these options to any child translators.

The legal values for FS_OPTION depends on FILESYS, but some common ones are:

--readonly

--writable

--remount

--sync[=INTERVAL]

--nosync

If no options are supplied, FILESYS' current options are printed.

Copying
*******

The Hurd is covered under the GNU General Public License, as is this manual.

GNU General Public License
==========================

     [file gpl.texinfo not included]