Provided by GNU Savannah

Savannah CVS Surfing - project hurdextras - View of /documentation/using_gnuhurd.texi

[hurdextras] / documentation / using_gnuhurd.texi
cvs -d:pserver:anonymous@cvs.sv.gnu.org:/sources/hurdextras co documentation/using_gnuhurd.texi
(to check out web pages for a project, replace /sources with /web in the path above)

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.15 - (download) (as text) (annotate)
Fri Jan 31 18:25:48 2003 UTC (6 years, 9 months ago) by tomhart
Branch: MAIN
CVS Tags: HEAD
Changes since 1.14: +86 -80 lines
2003-01-31 James A. Morrison <ja2morri@uwaterloo.ca> CVS:
        * using_gnuhurd.texi (Configuring): -c creates files not
	  translators.
          Add comment about multiple network cards.
        * using_gnuhurd.texi (Top): Remove the extra copying section.
        * using_gnuhurd.texi: Fix some minor spacing issues.

----------------------------------------------------------------------
documentation/ChangeLog documentation/using_gnuhurd.texi CVS:
----------------------------------------------------------------------
\input texinfo  @c -*-texinfo-*-
@setfilename using_gnuhurd.info
@c Get the Hurd version we are documenting.
@include version.texi
@c Unify all our little indices for now.
@defcodeindex sc
@syncodeindex sc cp
@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex tp cp
@syncodeindex pg cp

@dircategory Kernel
@direntry
* GNU/Hurd: (gnuhurd).  Using the Official GNU Operating System
@end direntry

@ifinfo
Copyright @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.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries a copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore

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.
@end ifinfo

@setchapternewpage none
@settitle The GNU/Hurd User's Guide
@titlepage
@finalout
@title The GNU/Hurd User's Guide
@author Thomas Bushnell BSG
@author Gordon Matzigkeit
@author Matthew S. Grant
@author Thomas Hart
@page

@vskip 0pt plus 1filll
Copyright @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.
@end titlepage



@node Top, Introduction, (dir), (dir)
@comment node,   Next,   Prev , Top
@top The GNU/Hurd User's Guide

This file documents the usage of GNU/Hurd.  This edition of the
documentation was last updated for version @value{VERSION} of the Hurd.

@menu
* Introduction::                How to use this manual.
* Installing::                  Setting up Hurd software on your computer.
* Bootstrap::                   Turning a computer into a Hurd machine.
* Using::                       Getting comfortable as a user.
* PC Hardware Basics::          Learn a little about x86 hardware.
* Networking::                  Getting connected.
* Translators::                 Extending the Hurd filesystem hierarchy.
* Troubleshooting::             Some troubleshooting help. 
* Finding More Information::    Other sources of information.
* Helping Out::                 Helping us improve the GNU system.
* Copying::                     The GNU General Public License.
* Index::                       Guide to concepts and files.

@detailmenu
-----------------------
Introduction

* Audience::                    The people for whom this manual is written.
* Overview::                    Basic architecture of the Hurd.
* History::                     How the Hurd was born.
* Who Should Use the Hurd?::    Pros and Cons of the Hurd for various groups.
* Hurd Today::                  The status of the Hurd.                  
* Conventions::                 How to read this manual.

Installing

* Binary Distributions::        Obtaining ready-to-run GNU distributions.
* Archive Method::              Installing a snapshot release.
* Cross-Compiling::             Building GNU from its source code.

Bootstrap

* Bootloader::                  Starting the microkernel, or other OS's.
* Installing GRUB::             Install GRUB into the Master Boot Record.
* Server Bootstrap::            Waking up the Hurd.
* Shutdown::

Using

* The Shell::                   Some basic knowledge you need.
* Scripting with Bash::         An introduction to shell scripts.
* File Archivers::              Basics on archiving and compressing files.
* Administration::              Some basic Admin. things.
* Accessing the cdrom::         Get your data from cdrom.
* Accessing the floppy::        Get your data from floppy. 

PC Hardware Basics

* CPU::                            (Central Processing Unit)
* Power Supply::                   (+-5volts,+-12volts)
* Motherboard::                    (main board,system board, etc.)
* RAM::                            (Random Access Memory)
* Hard Drive::                     (IDE, SCSI, ATA, etc.) 
* Floppy Drive and CDROM::         (Removable Storage)
* Serial and Parallel Ports::      (for external devices)
* Video Cards::                    (VGA, AGP, ISA)
* PCI and EISA Slots::              (for internal devices)
* BIOS::                           (Basic Input Output System)

Networking

* Configuring::                 Configure your Network card.
* Accessing FTP::               Using the FTP protocol.
* Accessing NFS::               Using the NFS protocol.
* Web Surfing::                 Surfing the web in text mode.

Translators

* Invoking settrans::           Declaring how a node should be translated.
* Invoking showtrans::          Displaying how nodes are translated.
* Invoking mount::              Unix-compatible active filesystem translators.
* Invoking fsysopts::           Modifying translation parameters at runtime.

Troubleshooting

* Fscking the filesystem::      Repairing your disk after a crash.    
* Booting and GRUB::          

Finding More Information

* The info pages::              GNU's documentation.
* The man pages::               The traditional UNIX documentation.
* HOWTOs::                      Help on specific tasks.
* Websites of interest::        Websites supplying good Free documenation.
* Searching the web::           Searching the Internet for information.
* Mailing lists::               Getting help from other users.

Helping Out

* Basic CVS Usage::             Getting development files.
* Using gcc::                   Compiling programs.
* Makefiles::                   Compiling big programs.
* An Introduction to Texinfo::  GNU's documentation format.
* Debugging with GDB::          Using the GNU debugger.
* Reporting Bugs::              How to report problems.

@end detailmenu

@end menu

@node Introduction, Installing, Top, Top
@chapter Introduction
@cindex GNU Hurd

The @dfn{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.

@c FIXME:  Might we want to define `server' and `Mach' in a
@c glossary, and refer to those definitions here?

@menu
* Audience::                    The people for whom this manual is written.
* Overview::                    Basic architecture of the Hurd.
* History::                     How the Hurd was born.
* Who Should Use the Hurd?::    Pros and Cons of the Hurd for various groups.
* Hurd Today::                  The status of the Hurd.                  
* Conventions::                 How to read this manual.
@end menu

@node Audience, Overview, Introduction, Introduction
@comment node, next, prev, up
@section Audience
@cindex GNU/Hurd

This manual is designed to be useful to everybody who is interested in
using or administering a GNU/Hurd system.

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 @dfn{GNU/Hurd} workstation.  
Subsequent 
chapters describe day-to-day use of the system, setting up and using 
networking, and the use of translators.  

@c I'm including the explicit example for *absolute* newbies who might
@c otherwise type ``program --help''.
If you need help with a specific program, you can get a short explanation 
of the program's use by typing @kbd{@var{program} --help} at the command 
prompt; for example, to get help on grep, type @kbd{grep --help}.  
More complete documentation is available if you type @kbd{info @var{program}}; 
continuing with our example of grep, type @kbd{info grep}.

This manual attempts to provide an introduction to the essential 
topics for using a GNU/Hurd, or any free UNIX-like, system.  New 
users of GNU/Hurd and GNU/Linux often spend time learning what skills 
they must learn; for example, users must learn what tools are important, 
and what sources of information are most useful.  We introduce the reader 
to the skills and concepts that must be learnt, and tell the reader where 
to find further information.

@node Overview, History, Audience, Introduction
@comment node,  Next,  Prev,      Up
@section Overview
@cindex operating system
@cindex kernel 
@cindex GNU C Library 
@cindex POSIX
An operating system's @dfn{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; for instance, NFS and FTP use the same TCP/IP
communication protocol. NFS, FTP, and the TCP/IP servers are all 
separate user-space programs (don't worry if these programs 
are not familiar to you, you can learn about them if and when 
you need to).

The @dfn{GNU C Library} provides a @dfn{POSIX} environment on the Hurd, by
translating standard POSIX system calls into calls to the
appropriate Hurd server.

POSIX stands for Portable Operating System Interface.  POSIX
is a set standards defined by the IEEE.  Unix-like 
operating systems aim to be compliant or partially-compliant. GNU/Hurd
is as compliant as any other Unix-like operating system. That is why
ported applications, implementations of protocols and other essential
services have been available since the introduction of GNU/Hurd. But always 
remember: GNU's Not Unix. GNU/Hurd complies with POSIX,  but is 
constantly growing to address the limitations of Unix-like 
operating systems.

@node History, Who Should Use the Hurd?, Overview, Introduction
@comment node, Next, Prev,   Up
@section History
@cindex Richard Stallman (RMS)
@cindex GNU
@cindex Mach
@cindex RMS
@cindex Lites
@c FIXME: Include some history of Unix and Mach.

Richard Stallman @dfn{RMS} started @dfn{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@dots{} 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:

@display
``We are still interested in a multi-process kernel running on top of
@dfn{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].
@end display

@dfn{RMS} explains the relationship between the Hurd and Linux in @*
@uref{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.

These announcements made it clear that the GNU Project was 
getting a Mach microkernel as a component of the GNU System. 
Once Lites, a single-server 4.4BSD user land environment, had been
implemented on top of Mach, Mach-based systems became usable.
Members of the GNU Project then began hacking Mach for use with 
the GNU Project's multi-server kernel replacement.
The individuals involved with making Mach work with 
the GNU Project's multi-server kernel replacement were Thomas 
Bushnell, BSG., and Roland McGrath. The Mach microkernel was 
originally developed at Carnegie Melon University (CMU);  after 
development subsided at CMU, the University of Utah took over and 
continued adding  better drivers and fixing other critical 
deficiencies.

In the latest GNUmach release notes, kernel and glibc maintainer 
Roland McGrath clarifies the development history of the GNUmach 
microkernel.
@display
"When maintenance of Mach 3.0 at CMU waned, the University of
Utah's Flux Group took over in the form of the Mach4 project, 
and revamped much of the i386 machine support code in the course 
of their research. While at Columbia University, Shantanu Goel 
worked on using Linux device drivers in Mach, and later continued 
this work at the University of Utah.  Utah Mach4 became the seat 
of Mach development on the 3.0-compatible line, and the microkernel 
underlying the GNU/Hurd multiserver operating system.  When the Flux 
Group's research moved on from Mach to other systems, they
wanted to reuse the work they had done in hardware support and device
drivers; this work (and a whole lot more) eventually evolved into the
OSKit.  Meanwhile, when the Flux Group stopped maintaining Mach4, 
the Free Software Foundation's GNU Hurd Project had taken it up and 
produced the GNUmach release to go with the Hurd.  Since then, the 
Hurd has become an all-volunteer project whose developers are not 
paid by the FSF, and later GNUmach releases incorporating bug fixes 
and updating the Goel/Utah encapsulation of Linux device drivers have 
been made by volunteers including Okuji Yoshinori and Thomas Bushnell.

This bit of history explains some of why it was so easy to replace a 
lot of the GNUmach/Mach4 hardware support code with OSKit calls--in 
many cases the OSKit code is a direct evolution of the code originally 
in Mach4 that I was replacing, with the names changed and improvements 
Utah has made since the Mach4 days."  
@end display 

@node Who Should Use the Hurd?, Hurd Today, History, Introduction
@comment node, next, prev, up
@section Who Should Use the Hurd?
@cindex GNU/Linux
@cindex Debian
@cindex BSDs
@cindex GPL
@cindex Mach
@cindex microkernel

Firstly, a note for end-users: if you do not consider yourself 
``computer literate'', then you @emph{definitely} will not want to use 
the Hurd.  No official release of the Hurd has yet been made in many years, 
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. @dfn{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 @emph{now} @dots{} it is the system that you will use for these 
tasks in the @emph{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 GNU/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 GNU/Hurd systems and testing them for bugs, writing documentation, and 
translating existing documentation into other languages. At present, most 
GNU/Hurd documentation is available 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 GNU/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 @dfn{BSDs}.  GNU/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 (@pxref{GNU General Public License}) 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.  For example, the MS-DOS FAT filesysetem  
was not supported by GNU/Hurd until a developer wrote a translator that 
allows us to access this filesystem. In a standard Unix-like environment, 
such a feature would be put into the kernel.  In GNU/Hurd, this is 
done in a different manner and recompiling the kernel is not necessary, 
since the filesystem is implemented as a user-space program.

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 multi-threaded so that it runs
efficiently on both single processors and symmetric multiprocessors.
The Hurd interfaces are designed to allow transparent network clusters
(@dfn{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 GNU/Hurd systems.

@dfn{Mach} is known as a 1st-generation @dfn{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 example,
until recently, @emph{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 
@emph{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 recommendations of current 
operating system theory.  In addition, the Hurd's modular nature makes it much 
easier to understand than many other kernel projects.

@c I'm making a bit of an assumption about the Hurd being relatively-
@c easy to understand. I can't say that I understand the Hurd sources, or
@c those of Linux. But this _should_ be the case.

GNU/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 (the Linux filesystem), ufs 
(the BSD filesystem), and iso9660fs (the CD filesystem).  GNU/Hurd 
offers a developer the opportunity to make a substantial contribution to 
a system at a relatively-early point in its development.

@node Hurd Today, Conventions, Who Should Use the Hurd?, Introduction
@comment node, next, prev, up
@section Hurd Today
@cindex Debian Project

The GNU operating system is alive and well today.  In 1998 Marcus Brinkmann 
brought the Hurd to the @dfn{Debian Project}.  This allowed GNU/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 Hurd's unique multiserver microkernel environment.  There is  also work
on porting the Hurd to two other micro-kernels and another architecture.

Debian GNU/Hurd has been Debian's most active non-Linux port.  The user 
applications that are ported to GNU/Hurd are very current and are actively
being improved.  Development of GNU/Hurd within the Debian project has also
contributed to incremental development releases on sets of CDs.  Also,
new developers are allowed to get the source code to the Hurd from anywhere
on the planet via Debian's packaging tool apt, and can get an even-more 
recent snapshot release from 
the the GNU project's @uref{ftp://alpha.gnu.org,alpha.gnu.org} server. 

As far as a multi-server microkernel based operating systems are 
concerned: GNU/Hurd has had it's share of critisim.  Many people 
have criticized the Hurd for its lack of a stable release,
its design, which is unfamiliar to those used to monolithic kernels 
such as Linux and the BSD kernels, and its connection to the strong 
ideals of the GNU Project; however, GNU/Hurd is a cutting-edge 
operating system. Other operating systems with designs similar to 
GNU/Hurd are QNX and Sawmill.  QNX is meant for embedded systems and 
many of the GNU Projects most famous programs are available for it .   
Sawmill was a research project set up by IBM.  It was never released 
outside the academic community.  Sawmill is a version of the Linux 
kernel running as multi-server on top of the L4 microkernel.  It 
used some of the same ideas as GNU/Hurd but with members of the 
@uref{http://www.l4ka.org,L4} Project influencing some of there 
research in microkernel based technology.

@node Conventions,  , Hurd Today, Introduction
@comment node, next, prev, up
@section Conventions
@cindex Conventions

We often show command prompts in this manual.  When doing so, the command 
prompt for the @dfn{root user} (System Administrator) includes a '#' 
character, and the command prompt for a regular user includes a '$' 
character.  For example, if we were discussing how to shut down the system, 
which only the root user may do, the prompt may look like this:

@example
# halt @key{ENTER}
@end example

When discussing how to list the contents of a directory, which regular users 
can do, provided they have read permission for the directory (more on this 
later), the prompt may appear as:

@example
$ ls @key{ENTER}
@end example

Prompts may include additional characters, for example:

@example
bash-2.05# mke2fs -o hurd /dev/hda3 @key{ENTER}
@end example

Hyperlinks in this manual look like this: @uref{http://www.gnu.org/}.

A @dfn{definiton} is typeset as shown in this sentence.

There is a footnote at the end of this sentence. @footnote{This is a 
footnote.}

The names of commands are appear like this: @command{info}.  Files are 
indicated like this: @file{README.txt}.

This document includes cross-references, such as this one to the 
@xref{GNU General Public License}, and this parenthetical one to the 
@pxref{GNU General Public License}.

@node Installing, Bootstrap, Introduction, Top
@comment node, next, prev, up
@chapter Installing
@cindex GNU/Hurd
@cindex ported
@cindex Porting

Before you can use @dfn{GNU/Hurd} on your favorite machine, you'll 
need to install its base software components.  Currently, the Hurd 
only runs
on Intel i386-compatible architectures (such as the Pentium), using the
GNU Mach microkernel.

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
@dfn{ported} to your architecture. @dfn{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 @email{bug-hurd@@gnu.org} in order 
to coordinate the effort.

@menu
* Binary Distributions::        Obtaining ready-to-run GNU distributions.
* Archive Method::              
* Cross-Compiling::             Building GNU from its source code.
@end menu

@node Binary Distributions, Archive Method, Installing, Installing
@comment node, Next, Prev, Up
@section Binary Distributions
@cindex binary distribution
@cindex Free Software Fondation
@cindex CopyLeft

By far the easiest and best way to install GNU/Hurd is to obtain a Debian
GNU/Hurd @dfn{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 (@pxref{GNU General Public License}).  Please consider sending
a donation to the @dfn{Free Software Foundation} so that we can continue 
to improve GNU software.

You can order Debian GNU/Hurd on a CD-ROM from 
@uref{http://www.copyleft.co.nz/,CopyLeft}
or you can also FTP the complete GNU system in iso format from your 
closest GNU mirror,or @uref{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 @file{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
@uref{http://www.gnu.org/gnu/linux-and-gnu.html, GNU/Linux} systems or
other Unix-like systems before, GNU/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 GNU/Hurd.

If GNU/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.

@c *Personally*, I'm all for learning with books, but is non-Free
@c documentation (K&R, Running Linux, Richard Stevens' books) officially 
@c considered evil by GNU? 
@c mg: I would think so, only because of the authors signing publishing
@c deals and allowing the access to the material to be restricted. Check
@c out the reasoning for RMS's decision to make the GFDL  

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


@node Archive Method, Cross-Compiling, Binary Distributions, Installing
@comment node, Next, Prev, Up
@section Archive Method
@cindex tarball
@cindex GRUB
@cindex module

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:

@enumerate
@item
A @dfn{tarball} of a snapshot release.

@item
1 gb or less of free unpartitioned drive space.

@item
A GRUB bootdisk.
@end enumerate

Using 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. Let's say I made a 
partition called /dev/hda3 I would format it this way:
@example
bash-2.05# mke2fs -o hurd /dev/hda3
@end example

After this is done you can mount the partition and extract your archived 
snapshot into the directory in which the partition is mounted. In this 
example, we mount the partition on @var{/mnt}, but you can mount your 
partition anywhere you choose.
@example
bash-2.05# mount /dev/hda3 /mnt
bash-2.05# cd /mnt
bash-2.05# tar zxvpf ~/gnu-latest.tar.gz
@end example

After your done you should be able to reboot.  You must use the 
@dfn{GRUB} boot disk to boot the Hurd.  Once you've booted, you 
can finish the installation by running the @var{native-install.sh} 
shell script.

@emph{ @b{Note: } When you are 
booting the Hurd for the first time, you must give GRUB the single-user 
option (-s), as in the following example.   Also note that the first 
long @dfn{module} entry is all on one line. }

@display
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)
@end display

@node Cross-Compiling,  , Archive Method, Installing
@comment node,next,prev,up
@section Cross-Compiling
@cindex 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 @dfn{cross-compiling}, because it is done between two
different platforms.

@emph{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@dots{} 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 (@pxref{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 @emph{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 @email{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, and will help you figure out a way
that your cross-compilation can benefit Hurd development.  After that,
don your bug-resistant suit, and read the @file{INSTALL-cross} file,
which comes with the latest Hurd source code distribution.  The
instructions in @file{INSTALL-cross} are usually out-of-date, 
but they contain some useful hints buried amongst the errors.

@node Bootstrap, Using, Installing, Top
@comment node, Next, Prev, Up
@chapter Bootstrap

Bootstrapping@footnote{The term @dfn{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.

@menu
* Bootloader::                  Starting the microkernel, or other OS's.
* Installing GRUB::             Install GRUB into the Master Boot Record.
* Server Bootstrap::            Waking up the Hurd.
* Shutdown::                    
@end menu

@node Bootloader, Installing GRUB, Bootstrap, Bootstrap
@comment node, Next, Prev,   Up
@section Bootloader
@cindex bootloader
@cindex microkernel

The @dfn{bootloader} is the first piece of 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.

@cindex GRUB
@cindex GRand Unified Bootloader
Currently, @dfn{GRUB}@footnote{The GRand Unified Bootloader, available
from @uref{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, the *BSD family, and DOS).

From the standpoint of the Hurd, the bootloader is just a mechanism to
get the @dfn{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. 
However, you don't need to know how this all works in order to use GNU.

@node Installing GRUB, Server Bootstrap, Bootloader, Bootstrap
@comment node,  Next,  Prev,  Up
@section Installing GRUB
@cindex menu.lst
@cindex GRUB

At the moment, you are booting the Hurd with a floppy disk.  Doing 
so regularly is not a good idea, since floppy disks are prone to 
failure.  This section will show you how to install GRUB into the 
master boot record of your hard-disk.

What you need are:

@enumerate
@item 
A GRUB boot floppy.
@item
A copy of GRUB installed on your hard disk.
@item
Knowledge of which partition contains GNU/Hurd.
@end enumerate

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

@example
bash-2.05# mkdir /boot/grub
@end example

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.

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

Now, you have two more things to do.  You must construct a @file{menu.lst} 
file to put in your @file{/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 @file{menu.lst} file

@display
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
@end display

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

When the boot menu of your GRUB floppy appears, press @key{c} on 
your keyboard.  This will put you at the GRUB command prompt.  
You need to start with the @command{root} command:

@example 
grub> root (hd0,0)
@end example

The @command{root} command in the above example tells 
GRUB that my GNU/Hurd system is installed on the first partition 
of the first drive.  After you press the @key{Enter} key, GRUB 
should print out something along the lines as @code{<ext2} and a 
bunch of numbers>.  This means that GRUB found your root filesytem. 
Next you need GRUB to load the kernel.  This is the tricky part.  
Heres what I have:

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

Once you press @key{Enter} again, you will see some more info.  
If you get an error, that just means you made a typing mistake, or 
picked the wrong root device for GRUB. 
There is no need to work: this will not make your machine explode.

Next, you need to enter the modules for GRUB to use. This is probably 
the trickiest part of booting the system.

@display
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)  
@end display

@emph{Note this should be all on one line, do not press @key{Enter} 
until the end.}

Next, type:

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

That first monster module line is a lot to type each time you want to 
boot GNU/Hurd. We can save ourselves a lot of time and effort by 
putting this information, along with all other relevant information, in 
the @file{menu.lst} file, as shown in the example above.

So, we open nano, type something similar to the example @file{menu.lst} 
file shown above, reboot the system, and @enddots{} the system freezes 
on boot. 
What went wrong?

The answer is that nano automatically inserts line breaks at the end 
of long lines, so our big monster module line is broken up into a 
form that GRUB cannot understand. 

There are two easy ways to solve this problem. First, you could create 
your @file{menu.lst} file using another editor, such as GNU Emacs, 
that does not automatically insert line breaks. Another example is 
to use the @key{\} character, which tells GRUB to read the next line 
as if it were part of the current line; you could type, for example:

@display
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)
@end display

GRUB would then interpret these five lines as one long line.

To fully understand all our module commands, you can check the Hurd 
Reference Manual, which should explain every detail.  These are very 
important for developers, as these commands can do many interesting 
things with the GRUB bootloader and the Hurd.  For instance the newest 
gnumach microkernel can use GRUB to debug it through the serial port 
on your computer.  GRUB can also boot your kernel and then fetch the 
rest of your system over the network.  This is partially implemented 
with GNU/Hurd but older Unix-like operating systems can do this easily.

@c FIXME: I'm not sure how to interpret that last sentance.

@c As soon as you start updating your system, by installing or rebuilding 
@c kernels and Hurd servers, the GRUB menus will get more complex.  
@c mg: I sure hope it doesn't

If you're still with me, then you should be able to safely install GRUB 
on your hard disk.  If you're confused, then you should consult the GRUB 
documentation.  You should be able to install GRUB by typing the 
following command at your GRUB command prompt:
 
@example
:grub> setup (hd0)
@end example

If this is successful, you should be able to press the reset button on your 
machine's case and remove
the GRUB floppy.  You just installed GRUB to the master boot record of the hard
disk! That's one task many people are scared to attempt.

@node Server Bootstrap, Shutdown, Installing GRUB, Bootstrap
@section Server Bootstrap
@pindex serverboot

The @code{serverboot} program has been deprecated.  Newer GNU Mach 
kernels support processing the bootscript parameters and boot 
the Hurd directly.

The @code{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 @code{serverboot}, the microkernel must start
@code{serverboot} as its first task, and pass it appropriate arguments.  
@code{serverboot} has a counterpart, called @code{boot}, which can be invoked 
while the Hurd is already running, and allows users to start their own complete
sub-Hurds (@pxref{The Sub-Hurd}).

@menu
* Invoking serverboot::         Starting a set of interdependent servers.
* Boot Scripts::                Describing server bootstrap relationships.
* The Sub-Hurd::                Running a Hurd under another Hurd.
* Invoking boot::               How to use the boot program.
@end menu

@node Invoking serverboot, Boot Scripts, Server Bootstrap, Server Bootstrap
@subsection Invoking @code{serverboot}

The @code{serverboot} program has the following synopsis:
@example
serverboot -@var{switch}... [[@var{host-port} @var{device-port}] @var{root-name}]
@end example

@c FIXME: serverboot should accept --help and --version, for consistency
Each @var{switch} is a single character, out of the following set:
@table @samp
@item a
Prompt the user for the @var{root-name}, even if it was already supplied
on the command line.
@item d
Prompt the user to strike a key after the boot script has been read.
@item q
Prompt the user for the name of the boot script.  By default, use
@file{@var{root-name}:/boot/servers.boot}.
@end table

All the @var{switches} are put into the @code{$@{boot-args@}} script
variable.
@var{host-port} and @var{device-port} are integers which represent the
microkernel host and device ports, respectively (and are used to
initialize the @code{$@{host-port@}} and @code{$@{device-port@}} boot
script variables).  If these ports are not specified, then
@code{serverboot} assumes that the Hurd is already running, and fetches
the current ports from the procserver, which is documented in the 
GNU Hurd Reference Manual.

@c There was a @FIXME: xref here for the proc server, but I think 
@c that can wait until _much_ later.

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

@node Boot Scripts, The Sub-Hurd, Invoking serverboot, Server Bootstrap
@subsection Boot Scripts
@pindex /boot/servers.boot
@pindex servers.boot

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

@node The Sub-Hurd, Invoking boot, Boot Scripts, Server Bootstrap
@subsection The Sub-Hurd
@cindex NeighborHurd
@cindex SubHurd

The @code{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:

@enumerate 1
@item
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.  @code{boot} understands the regular
@code{libstore} options (FIXME xref), so you may use a file or other
store instead of a partition.

@example
$ @kbd{dd if=/dev/zero of=my-partition bs=1024k count=400}
400+0 records in
400+0 records out
$ @kbd{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) @kbd{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
$
@end example

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

 @example
$ @kbd{settrans -c ./my-root /hurd/ext2fs -r `pwd`/my-partition}
$ @kbd{fsysopts ./my-root --writable}
$ @kbd{cd my-root}
$ @kbd{tar -zxpf /pub/debian/FIXME/gnu-20000929.tar.gz}
$ @kbd{cd ..}
$ @kbd{fsysopts ./my-root --readonly}
$
 @end example
 
@item
Create a new boot script (FIXME xref).
@item
Run @code{boot}.
@example
-$ @kbd{boot -D ./my-boot ./my-boot/boot/servers.boot ./my-partition}
[...]
@end example

@item
Here is an example using a hard drive that already has a GNU/Hurd
system installed on an ext2 filesystem on @file{/dev/hd2s1}:

@example
$ @kbd{settrans /mnt /hurd/ex2fs --readonly /dev/hd2s1}
$ @kbd{boot -d -D /mnt -I /mnt/boot/servers.boot /dev/hd2s1}
@end example

@item
See @pxref{Invoking boot} for help with boot.
@end enumerate
 
Note that it is impossible to share microkernel devices between the two
running Hurds, so don't confuse your sub-Hurd with your main GNU/Hurd 
system.  When you're finished testing your new Hurd, then you 
can run the @code{halt} or @code{reboot} programs to return 
control to the parent Hurd.

@c FIXME: the `don't get any funny ideas' comment is confusing.  Am
@c I genuinely in some sort of danger if I contemplate sharing
@c microkernel devices between two running Hurds?
@c  tb: not if you know what you are doing.  But there is no clever
@c  device mediation going on.  Two hurds, with two filesystems writing
@c  the same partition, will wreak havoc.  Two hurds reading from the
@c  same terminal device will not share nicely.

If you're satisfied with your new Hurd, you can arrange for your
bootloader to start it, and then reboot your machine.  You will 
then 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).

@node Invoking boot,  , The Sub-Hurd, Server Bootstrap
@comment node, next, prev, up
@subsection Invoking boot
@cindex boot
 
Usage: boot [@var{option}@dots{}] @var{boot-script} @var{device}@dots{}
@table @code
@item --kernel-command-line=@var{command line}
@itemx -c
Simulated multiboot command line to supply.

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

@item --boot-root=@var{dir}
@itemx -D
Root of a directory tree in which to find the files specified in
@var{boot-script}.

@item --interleave=@var{blocks}    
Interleave in runs of length @var{blocks}.
 
@item --isig
@itemx -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.

@item --layer
@itemx -L
Layer multiple devices for redundancy.

@item --single-user
@itemx -s          
Boot into single user mode.

@item --store-type=@var{type}
@itemx -T
Each @var{device} names a store of type @var{type}.
@end table
 
Mandatory or optional arguments to long options are also mandatory or optional
for any corresponding short options.
If neither @option{--interleave} or @option{--layer} is specified, multiple
@var{device}s are concatenated.



@node Shutdown,  , Server Bootstrap, Bootstrap
@comment node, next, prev, up
@section Shutdown
@scindex halt
@scindex reboot

You can shut down or reboot your GNU/Hurd machine by typing these commands:
@example
bash-2.05# reboot <ENTER>
@end example

@example
bash-2.05# halt <ENTER>
@end example
In a matter of seconds it should tell you that it is in a type loop and
pressing @key{ctrl}, @key{alt}, and @key{Delete} at the same time will 
make the system reboot.  It is now safe to shut the computer off.

@node Using, PC Hardware Basics, Bootstrap, Top
@comment node, next, prev, up
@chapter Using
@cindex command line
@cindex Bash
Now that you have GNU/Hurd installed and booting, you're probably wondering
"What can I do with it?"  Well, GNU/Hurd is capable of being a console based 
workstation.  The X Window System is known to work, but is not required in 
order to learn how to use GNU/Hurd.  This chapter is intended to get you 
acquainted to the @dfn{command line} of GNU/Hurd.  You should read the Hurd 
FAQ 
and also have a working knowledge of @dfn{Bash}, the GNU shell.  
If you are not familiar with this material, you can read @pxref{The Shell} 
for a brief introduction.

@menu
* The Shell::                  Some basic knowledge you need.
* Scripting with Bash::        Introduction to shell scripts.
* File Archivers::             Basics on archiving and compressing files.
* Administration::             Some basic Admin. things.
* Accessing the cdrom::        Get your data from cdrom.
* Accessing the floppy::       Get your data from floppy.           
@end menu

@node The Shell, Scripting with Bash, Using, Using
@comment node, next, prev, up
@section The Shell
@cindex login 
@cindex cp
@cindex mkdir
@cindex cat
@cindex ls
@cindex cd
@cindex mv
@cindex rm
@cindex rmdir
@cindex df
@cindex pwd
      
If you successfully installed GNU/Hurd and you are in multi-user mode,
you should have a login shell ready for you, which should look like this:

@display

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 

@end display

You can go ahead and type @code{login root}@key{<ENTER>} to get started.  

What you need to know for using GNU/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 GNU/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,
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 filesystem and the data
on the filesystem.  This is called bash (Bourne again shell)@footnote{This is 
a pun on the name of the original Unix shell, the Bourne shell, and the 
Christian idea of being ``born again''.}.  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 the 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:~/$".)

@c FIXME: Starting with ``At this prompt, ...'', the above paragraph
@c becomes unclear (at least to me).

@example 
bash-2.05$
@end example

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

You may notice that many commands are abbreviations. The tradition of 
Unix-like systems dictates that commands take this form. Since the user 
is expected to type many commands into the shell, the commands are kept 
succinct so that fewer keystrokes are required. The side effect, of course, 
is many command names that are confusing at first sight.

@example
bash-2.05$ mkdir docs tmp sources <ENTER>
@end example

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

@example
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. 
@end example

There is another short cut, @code{ cd ../} This puts you in the directory 
above the one
you're currently in.
 
There are many ways to view a file, but we'll use the most common command 
called @command{cat} @footnote{An abbreviation for @emph{concatenate}, since 
@command{cat} can be used to concatenate files.}.

@example
bash-2.05$ cat README | less <ENTER>
@end example

You may wonder what @code{ | less} mean. We use the | (pipe symbol) to take 
the output of @file{README} and feed it to the @command{less} command.  
@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 @key{q} to quit @command{less}. 

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

Typing, 

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

will copy @file{README} and @file{chapter1.txt} to the @file{foo1} directory.  
Here are a few good options to remember:

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

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

@c FIXME: I'm for taking the -f out of the example. Passing -f to cp
@c is a little esoteric for beginners, IMHO, and the explanation 
@c doesn't add a lot of information.

To rename or move a file or directory you would use the @command{mv} (move) 
command. 
Be careful, because @command{mv} is a very powerful command.  You can lose 
data if 
you're not careful about what you do.  To rename a file or directory you 
would type, for example:

@example 
bash-2.05$ mv foo1/ foo2 <ENTER>
@end example

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

I'll bet you're saying, "I'm doing all this work, but how do I view my 
directories?"
You answer would be the @command{ls} (list)command.  The @command{ls} command 
also 
has many options.

@example 
bash-2.05$ ls -al <ENTER>
@end example

The two options I have here are used more often than any others.  The 
@code{-a} 
will show us all hidden files in the current directory.@footnote{Important 
files are 
often hidden, to prevent the user from accidentally deleting them.}  The 
@code{-l} option tells us to display the directory in long format.  
This means it shows us the date modified, file size, file attributes, etc. of 
all 
files.  

A user will also notice that there are files with dots 
in front of some files in thier home directory.  The dotted files are
typically hidden configuration files. The user will also notice a dot,
followed by two dots. In the unix file system a dot represents the 
current directory. The two dots represent the directory above your 
current working directory. Examples of using these dots are common in
building software.
 
@example
bash-2.05# ../configure # This runs configure from the directory above.
bash-2.05# ./program    # This runs program from current directory.
@end example

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

@example
bash-2.05$ rm README <ENTER>
@end example

Now, @command{rm} with some options:

@example
bash-2.05$ rm -rf foo2/ <ENTER>
@end example

The second example is very powerful.  The @code{-r} means ``recursive'' and 
the 
-f means ``force.''  This removes all the contents of @file{foo2}, without 
prompting the user for confirmation.

These are only the basic commands to get you started@dots{} there are many, 
many
two- and three-letter commands.  The more you use GNU/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.

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

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

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

If your prompt is not telling you what directory you are in, you can use the 
@command{pwd} (present working directory) command:
@example
bash-2.05$ pwd <ENTER>
/usr/src 
@end example 

As a final note, always remember: @emph{@command{info} is your friend on 
GNU/Hurd.}

@node Scripting with Bash, File Archivers, The Shell, Using
@comment node , next , prev, up
@section Scripting with Bash

These next few paragraphs are to aquaint the user of GNU/Hurd with 
extended shell capabilities. The bash shell is a very powerful program.
You may have seen the term "Shell Programming", well that is what Bash
can be used for. The shell can be used to write scripts to automate a 
handful of commands into one file. The start of a typical shell script 
will look like this:


@example
#!/bin/bash
# The above line has to be the very first line of your
# script. If it's not it is taken as a comment.
#
# This is a comment
uname -a ; df /

echo This is a shell script

uptime &&   

cat /etc/fstab
@end example

The very first line is a interesting one. The @command{#!/bin/bash}
is to notify the shell of what program to use to run the script.
The next two lines are comments, the '#' character is used to allow
us to type important information that the script won't execute.
Finally we get to the command @command{uname -a} which will tell
us the operating system we are using, with the -a option it tells
us everything we need.  Following the first command is the ';' character
which tells bash there is a compound command. The semicolon will 
tell bash to execute the command on the left first, then the right.
The '&&' symbols after "uptime" in the above script tell bash not to
execute the next command until the uptime command is complete. The
difference between the ";" and the "&&" is the first character will
spit out a error and then continue to the next command. 
In order to execute the above script the file 
attributes need to be changed to an executable format. To change
file attributes you use @command{chmod 755}.  The @command{chmod}
command is pretty tricky, so read the info and/or man pages to
fully understand the capabilities of @command{chmod}.

Bash has other time saving features, for instance the @command{export}.
You can export a couple of letters to represent a full path to a 
directory. The export command is typically used for this, here is a 
example:

@example
bash-2.05$ export SRC=/home/src
bash-2.05# echo $SRC
/home/src
@end example

In the above example we use the @command{echo} to tell us what the 
value of 'SRC' is. Without the '$' character the @command{echo} 
would just print out 'SRC'.  The @command{echo} is used extensively
in shell scripts to place text on our screen either for debugging 
purposes or to prompt the user for input. 

The great thing about shell scripts is that they have the capability
of doing things just as quickly as a compiled program.  A compiled
program is written, compiled, and then run.  The benefit of using
a script is it is written then interpeted by the shell.  When scripts
get too large or complicated they are sometimes re-written in a compiled
language. The reasoning behind this is that the shell script can slow
the machine down the larger it gets, and take away resources that could
be better used elsewhere on the computer.  To get a better understanding
of "Shell Programming" there are numerous books and on-line documents
to be used. 

Your GNU/Hurd workstations is comprised of many shell scripts.  For
instance when you login to the shell a couple scripts set up your
enviroment for you.  The scripts .profile and .bashrc set things
such as 

@enumerate
@item
PATH : This is typically ":/bin:/sbin:/usr/bin:/usr/sbin:/usr/X11R6/bin"
       and can be modified to suit your needs. Generally you programs
       will reside in "bin" or "sbin" directories. Instead of typing
       /usr/bin/gcc you can just type gcc and the computer knows where
       it is.
@item
PS1 :  This is a bash variable that sets the look of your prompt.
       When the PS1 variable is not set you just see bash-2.05$ as
       your prompt.
@item
MANPATH:  The MANPATH variable is used so that when man is evoked
          It knows where all the man pages live.
@item
alias : The alias command is used you disguise a command with anything
	your heart desires except another command. A user can alias
	the 'ls -a' to 'l' so at a bash prompt typing 'l <ENTER>'
	will evoke 'ls -a'
@end enumerate

As you get more comfortable with you GNU/Hurd workstation you will
end up customizing some of these values to suit your needs.

@node File Archivers, Administration, Scripting with Bash, Using
@comment node, next, prev, up
@section  File Archivers
@cindex tar
@cindex bzip2
@cindex gzip

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

@dfn{Archiving} is a method of packaging files.  It has been around 
since the early days of computing.  The @command{tar} command that we use 
when working 
with archives stands for ``tape archiver''. It was originally used to create 
archived 
files for backup on large tape drives.

Closely associated with archiving is the concept of @dfn{compressing}. Various 
algorithms 
can be used to pack data into a smaller format. Archives are often compressed 
before being 
distributed; for example, a tarball may have the extension @file{.tar.gz}, 
which means that 
the tarball is a @code{tar} archive that has been compressed using 
@command{gzip}. Most software 
that you try and install from source-code will be packaged this way.  I will 
try to give you 
some examples; if you're confused, always consult the info pages.

Let's say we get a @code{tar} file that has some documents you want to read.  
Make 
sure that you are in your home directory, then type:

@example
bash-2.05$ tar xv docs.tar <ENTER>
@end example

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

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

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

The @command{gzip} compression format is commonly used in the GNU system.  
Files with 
the extionsion @file{.gz} are associated with @command{gzip}.  The utilities 
@command{tar} and @command{gzip} work so well together that people 
have patched the tar command so that it can compress and decompress 
@command{gzip}ed 
files.  Note, however, that @command{tar} cannot be used to decompress 
@command{gzip}ed files that are not @command{tar} archives. 

@example 
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
@end example

In the first example, the @code{z} after the @command{tar} command is the 
option 
that tells @command{tar} that the file has been @command{gzip}ed.  The second 
example is the @command{gzip} command, using the @code{d} option to decompress 
@file{file.gz}.  @command{gunzip} is a command that is equivalent to 
@command{gzip -d}, but more intuitive.

@example 
bash-2.05$ gunzip file.gz <ENTER>
@end example

To compress a @code{tar} files, or any file, using @command{gzip},
 you would type:
@example
bash-2.05$ gzip -9 file.tar <ENTER>
@end example

The @code{-9} means best compression.  There are many options available for 
@command{gzip}.  A quick browse through the info pages will tell you 
everything you need to know.

Another common form of compression is the @command{bzip2} format. @code{tar} 
archives 
compressed using @command{bzip2} usually have the extension @file{.tar.bz2}.  
This format is known to be one of the best compression utilities.  
To extract a bzip2 file you would type:

@example 
bash-2.05$ bunzip2 file.bz2 <ENTER>
@end example

Like the @command{gzip} format, the @command{bzip2} format has many options.  
You will probably see @command{bzip2} compressing @command{tar} files.  The 
@command{bzip2} 
utility many other commands linked to it.  To extract a file that has been 
archived with @command{tar} and compressed with @command{bzip2}, you would 
do something similar to the following:

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

The @command{bzcat} command is a combination of @command{bunzip2} and 
@command{cat}.  
We @command{bzcat} the file, then pipe(|) the file to the @command{tar} 
command.  
Once again, I use @code{-x} to extract the file, and @code{-v} to see its 
contents.  
To compress a file using @command{bzip2} you would type:

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

This command compresses @file{file1.txt} to @file{file1.txt.bz2}.  You can 
also use 
the @code{'-9'} option for best compression.

Hopefully, this little chapter has gotten you more interested in using 
GNU/Hurd.
If you are still confused, please read the info pages for the command that's 
giving you trouble.  The command @code{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.  GNU/Hurd is 
just like music or sports: you can never learn enough. 
This chapter is meant to give you a stepping stone to freedom.

@node Administration, Accessing the cdrom, File Archivers, Using
@comment node, next, prev, up
@section Administration
@cindex su
@cindex root
@cindex adduser
@cindex passwd

After the last chapter, you're 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 legacy Unix systems.  The designers and developers want you, the user, 
to be able to do things that you cannot do on a traditional Unix-like 
operating 
system.

For the time being, though, you will have to deal with the root user.  

One reasonable request of the Unix-type gurus is making a normal user account. 
A 
normal user can only write to his or her home directory, and has limited 
access 
to system configuration.  The reasoning behind this is that a normal user can 
not mess
up the computer.  This is a decent compromise because the more we explore and
play, the more likely we'll lose a important file or make some other fatal 
mistake.  
So what we'll do is set up a user account for you.  You must be root to 
do this.

@example  
bash-2.05# adduser <ENTER>
@end example

That's it!  The computer will prompt you for a username 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:
@example
bash-2.05# passwd <USER_NAME> <ENTER>
Please Enter a Password:
@end example

There is a command that helps you become root while logged in as a normal 
user. 
This command is called @command{su}.  When you type @command{su}, you are 
required to enter a password (if you have one) for the root account. If a @command{ssh} (Secure Shell) server doesn't allow root logins, as root
you can @command{su} to a another user that has an access to that server.
When you are done being another user you type @command{exit} and your 
back as root.

@c FIXME: From ``This command works the other way ...'' on, this paragraph has 
@c me confused.
@c mg: I see what you mean

@example 
bash-2.05$ su <ENTER>
password:
@end example

There are many commands related to the Administering Unix-like operating
systems.  As a normal user, much 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.

@node Accessing the cdrom, Accessing the floppy, Administration, Using
@comment node, next, prev, up
@section Accessing the cdrom
@cindex settrans 
@cindex iso9660
@cindex cdrom
@cindex Joliet
Traditionally, Unix-like systems have used a command called @command{mount} 
to merge removable storage devices, such as CDs and floppy disks, into the 
file system. On GNU/Hurd, we don't @command{mount} anything.  The Hurd has 
a similar mechanism for accessing devices called "setting a translator".  

We use the @command{settrans} command to do this.  @command{settrans} is a 
program that aligns a type of Hurd server called a @dfn{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 CD, I first had to make the device.  Then I had to run the 
@command{settrans} command.  This had to be done as the root user (root is the only user that has these privileges). 

The term iso9660 is a standard set by the Industry Standards Organization.The ISO has set the universal access to CDROM media as standard number 
9660. Some systems use an extension to this standard called Joliet.  
The Joliet extension is typical of Microsoft Windows.  It is also 
supported on GNU/Hurd, GNU/Linux, and the BSDs.

@c FIXME: We should add more detail. If I were coming fresh from a diet of 
@c Windows beer, this would confuse the heck out of me.
@c mg: The brief iso description helps ?

@example
bash-2.05# cd /dev <ENTER>
bash-2.05# ./MAKEDEV hd2 <ENTER>
bash-2.05# settrans -ac /cdrom /hurd/isofs /dev/hd2 <ENTER>
@end example

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

Now you can type @command{cd /cdrom} and see the data on your CD.

@node Accessing the floppy,  , Accessing the cdrom, Using
@comment node, next, prev, up
@section Accessing the floppy
@cindex floppy
@cindex fat

This section will help you get some data off of your floppy disk. I note that
the @code{vfat (fat32)} and @code{msdos (fat16)} filesystems are currently 
not supported. The support will come eventually, but for now you can only 
access 
GNU/Linux floppies. You must be root to get to your floppy.

@example
joe@@hurd# settrans -a /floppy /hurd/ext2fs /dev/fd0 <ENTER>
@end example

Now you can head to the @code{/floppy} directory and see your data.


@node PC Hardware Basics, Networking, Using, Top
@comment node, next, prev,  top
@chapter PC Hardware Basics
@cindex dmesg
@cindex hardware

On Unix-like operating systems, it has always been a struggle for new
users to get their hardware configured.  Unix-like systems have a 
command called @command{dmesg} that allows users to view what hardware 
the kernel has detected.
The command @command{dmesg} spits out all that data that we see at boot to your
terminal. Unfortunately, the @command{dmesg} command has not been ported to 
GNU/Hurd. It should be ported in the near future. For now
we have to use a couple of GNU programs to get equivalent information: 

@display
bash-2.05# cat /dev/klog > dmesg & <ENTER>
bash-2.05# less dmesg <ENTER>
@end display  

As a user gets used to Unix-like systems, they should have
a decent idea what they have in their systems.  This section
should help new users discover some things, and hopefully educate 
to some extent.

@c >> Last I checked, dmesg hadn't been ported to GNU/Hurd yet!
@c >> Probably OK to leave in if we mention that it *will* be ported.
@c mg: ok I hope it comes soon.

A typical computer has many common pieces of hardware regardless 
of vendor.  A computer has these things in common:

@menu
* CPU::                            (Central Processing Unit)
* Power Supply::                   (+-5volts,+-12volts)
* Motherboard::                    (main board,system board, etc.)
* RAM::                            (Random Access Memory)
* Hard Drive::                     (IDE, SCSI, ATA, etc.) 
* Floppy Drive and CDROM::         (Removable Storage)
* Serial and Parallel Ports::      (for external devices)
* Video Cards::                    (VGA, AGP, ISA)
* PCI and EISA Slots::             (for internal devices)
* BIOS::                           (Basic Input Output System)
@end menu

@c This menu should follow the structure of the nodes! =)

Some systems have some of these pieces missing for certain reasons.
Typically the missing pieces are omitted because of cost, the hardware
being unneccesary, or other specialized reasons. 

@c >> You mean "unneededness", which isn't a word! How about 
@c "... because of 
@c >> cost, the hardware being unneccessary (sp?), or ...".
@c mg: I see

@node Motherboard, Floppy Drive and CDROM, PC Hardware Basics, PC Hardware Basics
@comment node, next, prev, up
@section Motherboard 

If your computer came with a printed manual, that manual will be 
very helpful; however, it will probably not tell you everything that 
you need to know. A person with 
their very own screwdriver can open up a computer and view some of the 
hardware. Just by looking at a certain card, you can get a lot of
important information.  On modern computer hardware, vendors are doing
a better job at labeling their products. This is a great thing now 
that we have the Internet and search engines. Now, a person can write
down some things that they see on a certain computer card, type
that information into a search engine, and, in a matter of seconds, 
find out everything they need to know.
 
The @dfn{motherboard} lies at the heart of your computer's hardware.  The name 
 ``motherboard'' comes from the fact that all other pieces of hardware are 
 connected to this board.
 
The motherboard is a large circuit board.  It will have slots in which you 
may add other chips, such as a video card or a network card.  When you see 
a computer advertised, and the advertisement mentions the number of 
expansion slots the motherboard has, it is referring to these slots.
 
The motherboard also has slots for RAM (memory) chips and CPUs.  The number 
of slots for RAM chips determines the extent to which the computer's memory 
is upgradeable.  As for CPUs, if your friend tells you that her computer is 
 a dual-processor machine, that means that the machine's motherboard has slots 
 for two CPUs, and that there is a CPU in each slot.
 
Other pieces of hardware that connect to the motherboard are power supplies, 
cooling fans, and disk drives.  Together, your computer's hardware provides 
you with a platform on which you can run a complete operating system.
      

The motherboard has many chips all connected by SMT(surface mount 
technology) wiring.  SMT is a technology that is used to connect 
tiny wires, transistors, diodes, capacitors, etc.  The components
collectively communicate with the CPU, Devices, and the BIOS. 
The Motherboard uses a IRQ(Interrupt ReQuest) controller to know
which devices can interrupt the CPU to send of receive data.  
For instance a Harddisk will have lower IRQ number than a keyboard.
The reasoning behind this is the keyboard is constantly being used
whereas the harddisk only gets written to or read from periodically.
A typical motherboard has 14 IRQ's, newer ones are giving the user
more.

@c >> First sentence is awkward. Perhaps, "If your computer came with a 
@c >> printed manual, that manual will be very helpful; however, it 
@c >> will probably not tell you everything that you need to know." ?
@c mg: Ok I used your sentence.

@node Floppy Drive and CDROM, PCI and EISA Slots, Motherboard, PC Hardware Basics
@comment node, next, prev, up
@section Floppy Drive and CDROM

Users need not be afraid of working on their computer. In the 
modern computer age manufacturers have made it very
easy for us. Everything is like a puzzle piece. Almost no piece 
of hardware can be put in upside down or reversed. The hardest 
part of it all is the cabling that goes from the motherboard
to the disks( Hard-drive, Floppy, Cdrom ). 

@c >> Watch "their" -- it is plural, and "a user" is singular. Either, 
@c >> "Users need not be afraid of working on their computers.", or 
@c >> "You should bot be afraid to work on your computer." =)
@c mg: Thanks, you'd think english was my second language.

When taking apart your computer for the first time, it is always
good to have a magic marker or some sort of writing utensil handy.
It is a good idea to mark your cables as you pull them out just
in case you have to stop working ,for example, to take out the dog. 
When you get back to to what you are doing you'll have some idea of 
what that cable belongs to. Another important thing to remember
is on the cables that go to your internal devices always have a 
red line representing pin one. You should never try to do two
things at the same time, this could make things more confusing.

@c >> Remember ","'s when appropriate.
@c >> RE: "in case you get sent off to take the dog out", how 
@c >> about, "in case you have to stop working, for example,  
@c >> to take the dog out"
@c mg: Thanks again, makes more sense now.


@node PCI and EISA Slots, Video Cards, Floppy Drive and CDROM, PC Hardware Basics
@comment node, next, prev, up
@section PCI and EISA Slots


An internal device is usually a hard disk drive, floppy disk drive,
CD drive, video card, network card or other important add-on.  
The disk drives are connected to the motherboard with
ribbon cables. The video card, network card, and possibly a 
modem are inserted in slots on the motherboard. Slots are called 
PCI, EISA, and AGP.

@node Video Cards, Hard Drive, PCI and EISA Slots, PC Hardware Basics
@comment node, next, prev, up
@section Video Cards

The AGP (advance graphics port) slot is for video cards only. EISA
(Enhanced Industry Standard Architecture) slots are for older 16-bit 
devices. You won't see that many EISA slots on todays motherboards.
More favorable are PCI(Peripheral Component Interconnect) slots these 
are the most abundant on todays motherboards because they are for 
32bit devices. The PCI slots are usually beige in color and are 
smaller than the longer black near obsolete EISA slots. 

@node Hard Drive, CPU, Video Cards, PC Hardware Basics
@comment node, next, prev, up
@section Hard Drive

The cabling connecting the disks to the motherboard are considered
IDE(Intergrated Drive Electronics) ribbon cables.  The motherboard
also has a special cable for your floppy disk drive. Both the ide
and floppy controllers should be labeled in very small print on 
your motherboard. The controllers should also have very small numbers
on the ends to tell us where pin one is. The cables will have a red
line to match pin one on the controller to pin one on the disk drives.
If your lucky your disk drives and cables will be brand new so none
of this will matter and they will only be allowed to connect the
right way.

Each IDE controller will allow you to connect two devices. The two
devices are considered master and slave. The master is always the
first or only drive on a IDE controller. Master drives are usually
bootable and contain the operating system's bootloader and kernel.
A slave drive can be a CDROM or another Hard disk. Some operating
systems are fussy about where they reside. It is generally a good
idea to have a operating system booting off of a master harddrive.
This isn't written in stone, Alot of software developers will have
multiple operating systems on a single computer.  Yet they usually
put there bootloader on the master ide drive along with a couple of
operating systems.   

@c >> Some explanation of "master" and "slave" would be helpful to the re
@c der.

The motherboard usually has two IDE controllers; a primary and 
secondary. We are allowed a total of four IDE devices cabled off 
of our motherboards. Some
of the newer motherboards are being manufactured with up to four
ide controllers.  A typical machine might have one cable connecting
a hard disk off of the primary ide contoller.  The machine could
have the cdrom drive connected with a cable to the secondary ide
controller.  The machine might even have the cdrom drive connected
as a slave on the primary ide controller. A very important way
of connecting these devices this way are small jumpers on the
disk drives. There should be clear instructions on the disks drives
on how these jumpers should look for a certain configuration. The
jumper selection area on the hardisk should look similar to the 
figure below.

@display
 MASTER SLAVE CABLE SELECT  
    |----------|
    | o  o  o  |  
    | o  o  o  |
    |----------|
@end display

@c  I have to figure out how to add this without texinfo squashing it.

@c >> I know what you mean here, but only because I once had to fiddle 
@c >> with master/slave settings. I think we should either have some
@c >> further explanation of what the labelling would look like, or 
@c >> an illustration (I was looking at the @image Texinfo command; it
@c >> inserts a PDF/EPS into HTML/PS/PDF output, and ASCII art into 
@c  >> info files. This probably wouldn't be too hard a thing to 
@c >> do some ASCII art of.)
 
If your new disk is going to be a master on the secondary ide
controller **,** you need to make sure these jumpers are set correctly.
If the jumpers are wrong and your cables are backwards you computer
will not work the way you expect it too.

@c >> [1] Need a "," or ":".

@node CPU, RAM, Hard Drive, PC Hardware Basics
@comment node, next, prev, up
@section CPU

The devices connected through slots, and disks connected to the 
controllers all end up communicating with the CPU. These devices
communicate via the ``bus''. The term ``bus'' comes from the 
fact that the data is sent down wires on the motherboard
to the CPU all at once. You sometimes hear the term "I have a hundred
megahertz bus"; this is the speed the data is traveling down
the bus to the CPU. Megahertz(MHZ)is also the measurement of speed 
of a CPU. A CPU can be found in a slot on the motherboard. The
CPU is either in slot form or in a ZIF(Zero Insertion Force)socket.  
Their are different types of ZIF configurations for certain 
CPUs. The ZIF sockets are usually labeled socket 8, socket 7,
socket 3, etc. The slot based CPU are primarily for Pentium II and
Pentium III CPUs. The very new CPUs use a new ZIF configuration
called PGA(Primary Grid Array). The PGA sockets are usually
for the Athlon and Pentium 4 processors. A ZIP socket makes it 
very easy to replace the CPU.  With a little lever on the side
of the socket a CPU can easily be replaced.  All of these 
configurations regardless of CPU have heat sinks with fans built
into them.  The fan and heat sink play an important role. The 
heat sink keeps the CPU from burning up and overheating your 
computer.  If you try and use a computer with out a working 
fan or without a heat sink your likely to run into sporadic errors.
The errors can range from software errors to the computer restarting 
by itself.

@c >> [2] They don't use the *term* bus to communicate, they use 
@c >> a thing called a bus. How about, "... via a bus.  The term 
@c >> "bus" comes from ..." ?
@c mg: ok sounds good

@c I think we need pictures for the CPU section. I have a bit of an 
@c idea of what you mean from my brief forays into the inside of my 
@c box, but not a great one. Do you have a digital camera? I could 
@c use a quickcam to take some pictures of hardware, but the quality 
@c would be nothing to write home about. =)

@node RAM, BIOS, CPU, PC Hardware Basics
@comment node next, prev, up
@section RAM

While data is being worked on by the CPU the machine also uses
RAM to store temporary data that the machine needs. RAM is one
important component that allows us to use a computer that multi-tasks.  
The term multi-tasking is simply doing more than one thing at the same 
time.  We should also know that if we don't have
enough RAM for what we need to do, a computer will not multi-task
efficiently. RAM is mounted on the motherboard in DIMM and/or SIMM
slots. The RAM can only go in one way.  A typical problem a person
can have with RAM is not putting it in completely. Another problem
is pushing the RAM too hard and cracking the motherboard. If either
situation happens, when you start your computer you will get no
picture, beeps, or any response at all. A DIMM stands for Dual 
Inline Memory Module. The DIMM is the most typical of newer mother-
boards. The SIMM which stands for Single Inline Memory Module is 
not seen as much as the DIMM. The SIMM has a slower speed than the 
DIMM. The SIMM is seen on most older motherboards but they can both
coexist together. The problem with the two different RAM Modules
coexisting is the SIMM can only work with 66MHZ bus systems.  If
you have a DIMM that is rated for 100MHZ systems they will default
to 66MHZ to live peacefully with the other RAM. When the bus speed
is defaulted to 66MHZ, this can actually change the CPU speeds on
some motherboards. Other differences between memory modules are the
pins. A DIMM should have 168 pins while the SIMM will only have 72 pins. 

@c >> [3] I don't know if "RAM" is a term we can/should use; I think 
@c that 
@c >> "RAM" is more the Windows term, and UNIX types say "memory" or 
@c "core".
@c >> I'm not completely sure of this, though. 
@c >> mg:In the hardware world RAM is RAM we have DRAM, SDRAM, RAMBUS,
@c    mg:DDR RAM, EDO RAM. To be OS independant I'll use the term RAM to
@c    mg:indicate a RAM MODULE.
@c >> Also, RAM is only of thing that makes us able to multi-task. 1
@c    We also 
@c >>need interrupts, and a multi-tasking operating system
@c mg: You are right I just need to find a clear way to explain
@c >> [4] Reading this, I find myself waiting for a "; for example, ". Is 
@c this 
@c >>a dig at DOS 6.22/Win3.1 for having co-operative multi-tasking?
@c mg: It's not really a dig, I'm just trying to explain that RAM is 
@c one of
@c the very important things or system performance regardless  of OS. 

@node BIOS, Power Supply, RAM, PC Hardware Basics
@comment node, next, prev, up
@section BIOS 

The BIOS is another good place to find information about the computer's
hardware. The BIOS is the motherboard's little brain. It holds the data
in the machine's CMOS (Complimetary Metal Oxide TranSistor) which is
sort of like long term storage.  The programming in the CMOS of the
BIOS holds data such as hard disk information (Primary or Secondary,
Master or Slave, Heads, Sectors,etc). It also holds the date, time,
and some RAM-related information.  A user can access the BIOS only
at boot time. Usually there is a message telling us to hit F1,F2 or
possibly Delete to enter setup. There are many confusing options in 
the BIOS. A good idea is to have the manual for your motherboard when
dealing with any unknown features of the board. If a user changes some
thing that causes havoc on the machine there is always a option to
restore the settings to factory default.  This can be a savior if we
change too many things and forget what we did.

@node Power Supply, Serial and Parallel Ports, BIOS, PC Hardware Basics
@comment node, next, prev, up
@section Power Supply

A computer's power supply has one connector that powers the mother-
board. The motherboard's power connector is a large white block with 
yellow, black, and red wires. The other connectors from the power 
supply are smaller D-shaped, with the same colored wires. The yellow
wires are rated +-13 volts.  The red wires are +-5 volts and the 
black ones are ground(0 volts).  Both the motherboard and internal 
device connectors cannot be put in backwards or upside down.  
One common problem is not pressing the power connectors in completely. 
The floppy disk drive has it's very own power connector that is also 
keyed (think key and keyhole) to go in correctly.  If your 
power supply is running hot or overheating, this can cause your 
machine to reboot and occasionally lock up.  To figure out if this 
is the case one can simply touch the back of computer, right above 
the power supply.  If it is hot to the touch this may be the clue you need.  
Power Supplies are also coming in different watt(240 thru 400)
ratings.  CPU's from different manufacturers require specific power 
requirements related to power supply and motherboard.  These 
requirements can sometimes add confusion when upgrading your system. 

@c >> [5] I don't know if you mean that it's impossible to accidently put 
@c >> these in incorrectly, or that if you put them in incorrectly, bad 
@c >> things will happen.
@c >>
@c >> Also "put in wrong" isn't proper English. "put in" is a verb, so we 
@c >> need an adverb, ie. "wrongly" or "incorrectly". =)
@c >>
@c >> [6] This clarifies the first part of [5].

 

@node Serial and Parallel Ports,  , Power Supply, PC Hardware Basics
@comment node, next, prev, up
@section Serial and Parallel Ports
 
On the back of your computer there are D-shaped connectors. The
D shaped connectors are for connecting external devices. Typically
a motherboard could have two serial ports and one parallel port.
The twenty-five pin parallel port is typically used for a printer 
or an iomega zip disk drive. The serial ports are the smaller fifteen 
pin ports. The serial ports are typically used for connecting external 
modems, palm devices, and possibly another computer. The uses of these 
ports are endless because they have been included with computers since
the beginning of the computer age.

@c This is preliminary, only the info file should contain ASCII art. =)

@verbatim
               _____          _____________
              /::::.\        /::::::::::::.\
              -------        ---------------
            Serial Port       Parallel Port
@end verbatim

A few technologies that haven't been mentioned so far are USB
(Universal Serial Bus), FireWire, and SCSI(Small Computer Systems 
Interface), which are beyond the scope of this text. The reason being 
is that they are technologies that are currently evolveing. The
oldest of the three mentioned is SCSI. SCSI has undergone many
revisions, we have SCSI-1, SCSI-2, Fast SCSI, Fast Ultra-Wide SCSI,
and others. SCSI is a very versitile technology. We see SCSI in
servers, high performance work stations and many other places.
If you plan to make a profession out of hardware support, SCSI
is a very important technology to learn.

When dealing with computer hardware it is always good to have as
much documentation as possible. The previous text is by no means
extensive, it is just an introduction.  The more work you do with
hardware, the easier troubleshooting becomes. Your natural senses
help alot with dealing with computer hardware. Smell is a very good
way of telling yourself that something is wrong. If you smell burning
semi-conductor this is a sure sign that some part in your system has
overheated to a point of failure. Vision is another good sense to 
use. If you see no picture on your monitor that could give a clue
as to what maybe wrong, such as a 
unplugged monitor, unseated RAM,
or other possibilities. Hearing is another sense that can be helpful.
If you hear more than one or two beeps at boot, this can tell you 
that you computers BIOS is warning you that something is wrong. Again
the more you get your hands dirty with computer hardware the more
comfortable and educated you will be.


@node Networking, Translators, PC Hardware Basics, Top
@comment node, next, prev, up
@chapter Networking
@cindex pfinet
@cindex ethernet
@cindex nic

In this chapter, you'll learn about the Hurd's networking features.  The 
Hurd's 
networking is a work in progress.  The services that the Hurd now has should 
be sufficient for the average user.  Available now are @command{ftp}, 
@command{nfs}, 
@command{telnet}, and, of course, web-surfing and e-mail.

@menu
* Configuring::                 Configure your Network card.
* Accessing FTP::               Using the FTP protocol.
* Accessing NFS::               Using the NFS protocol.
* Web Surfing::                 Surfing the web in text mode.

@end menu

@node Configuring, Accessing FTP, Networking, Networking
@comment node, next, prev, up
@section Configuring
@cindex network card
@cindex settrans 
@cindex ifconfig
@cindex eth0
@cindex hosts
@cindex resolv.conf
@cindex route
@cindex DHCP

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

@example
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>
@end example

In this example, the @command{settrans} command uses the following options:
@code{'f', 'g', 'c', 'a'}, and @code{'p'}.  The @code{-fg} forces anything 
that is attached to @file{/servers/socket/2} and @file{/hurd/pfinet} to go 
away.  
Next, the @code{-c} tells @command{settrans} to create 
@file{/servers/socket/2} if it doesn't exist.  The 
@code{-ap} 
tells the @file{/server/socket/2} and @file{/hurd/pfinet} 
to be both active and passive. The passive option will make the
configuration remain valid even after the reboots and shutdowns.  Here are the 
rest of the options:

@example
-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.
@end example

If you have more than one network card that you want configured you must
provide the options for each network interface on the same line.

@example
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 \
-i eth1 -a 10.0.0.5 -m 255.255.255.0 <ENTER>
@end example

Unfortunately, GNU/Hurd currently has no @dfn{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 GNU/Hurd machine. In 
describing 
this workaround, I'll assume that you are using a GNU/Linux system.

Boot GNU/Linux and log in as root. Type the following two commands, and 
observe their outputs:

@example
# 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
@end example

Note the @code{inet addr} and @code{Mask} from @command{ifconfig}, and the 
@code{Destination} field from @command{route}. In our example, the values 
are for the former two are 154.17.21.134 and 255.255.240.0; these are 
your IP address and netmask, respectively.

To get the value for your gateway machine, use the @command{ping} program 
on the host name corresponding to the @emph{default} destination from 
the output of @command{route}; in our example, we would type 

@example

$ ping MYrouter.Domain.ca @key{ENTER}

@end example

Note the IP address that @command{ping} reports; this is the IP address 
of your gateway machine. Reboot 
into GNU/Hurd, and use these three values to set your network translator as 
described above.

The next items to configure are our @file{resolv.conf} file and our 
@file{hosts} file.  
These are located in the @file{/etc} directory.  In fact, all GNU/Hurd's 
configuration 
files are located in the @file{/etc} directory.  The @file{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 networking files.  Here is an example:

@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)
@end example

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

After this is all set up, you should be able to use the @command{ping} 
@footnote{@command{ping} 
is a small program that we use to test whether or not we can talk to another 
machine.} program
on any host on the Internet and recieve a response. The next file to setup is 
the 
@file{/etc/hosts} file.  This 
file is used for machines you access frequently.  Instead if typing ip 
addresses for computers on your network, you edit @file{/etc/hosts} to allow you to just type the name of the computer you want to access.

@c FIXME: I think this could be a little clearer, but I don't know enough about
@c Unix networking to suggest a good solution at the moment.

@example
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 
@end example

Now I can access 192.168.1.5 by simply using its name, @emph{jojo}.  The same is true with @emph{mojo} also. For instance if I wanted to @command{telnet} into @emph{jojo}, I would type @command{telnet jojo}.
@footnote{With the proliferation of mischief on the Internet 
it is recommended you use the @uref{http://www.openssh.org,OpenSSH} 
suite to access remote computers.} 

@node Accessing FTP, Accessing NFS, Configuring, Networking
@comment node, next, prev, up
@section Accessing FTP
@cindex ftpfs

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 @code{ftpfs} server.  The other way 
is 
the traditional client-server method in which you login and use @command{get} 
and @command{put} commands.

The @command{ftpfs} translator is quite unique.  It allows you to have a 
remote 
FTP server accessible on a local directory.  You would then begin 
copying files to and from it as if it were a directory on your machine.

@example 
bash-2.05# settrans -ac /mnt /hurd/ftpfs / alpha.gnu.org
@end example

This command will set a translator for @command{ftpfs}.  The @command{ftpfs} 
translator places the root directory of alpha.gnu.org's anonymous ftp server 
on the @file{/mnt} directory. Now one can access the data as if it were a 
local 
filesystem.

The FTP protocol is traditionally accessed using a client program.
GNU/Hurd currently can use the one that comes with the GNU projects 
@code{inet-utils} package.   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, there are many more 
options, so read the info pages for some more complex operations.

@c FIXME: I don't understand (The Hurds... and many others).
@c mg: yup me too ;o/
@example
bash-2.05$ ftp <ENTER>
ftp> open ftp.gnu.org
@end example

You should then be prompted for a username and password.  You can log into
servers on the Internet who offer anonymous ftp access.  A anonymous ftp 
server is a server that allows anyone access to its 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 @code{get}, @code{put}, @code{mget},
 @code{mput}, @code{ls}, @code{pwd}, and @code{cd}.  These will work with any
standard ftp client.  The commands themselves are fairly self-explanatory.  
The 
@code{mget} and @code{mput} are for multiple files.  An example would be:

@example
ftp> mget *.tar.gz
@end example

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

@node Accessing NFS, Web Surfing, Accessing FTP, Networking
@comment node, next, prev, up
@section Acessing NFS
@cindex nfs
@cindex exports

The NFS protocol is a standard method for sharing files between Unix-like
workstations.  The server allocates directories that it wants to make
sharable through exporting.  Traditionally, the workstation mounts the 
shared directory onto the local filesystem.

For instance, Server1's @file{/etc/exports} file it says:
 
@code{/usr/src           mojo(rw,insecure)}

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

On GNU/Hurd, we access a network share by setting the @code{nfs} translator.  
This is done like so:

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

The remote shared directory is now visible on our @file{/mnt} directory.
We can then start copying, reading, and writing files as if the directory was on our own workstation.

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 what you do with it.

@node Web Surfing,  , Accessing NFS, Networking
@comment node,next, prev,up
@section Web Surfing
@cindex lynx
On GNU/Hurd, we can surf the web on the console.  The program that we use is
a text-mode web browser called Lynx.  The benefits of using a 
text-mode web browser are speed and simplicity.  In text-mode, you don't have 
to load any graphics, and you 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
@code{lynx}, then a URL like this example:

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

This starts us out with @file{www.google.com}.  To go to another URL, you type 
the letter, @key{g}, meaning ``Go.''  Lynx then prompts you for a address. To 
access 
a link on a web page, press the @key{->} key.  To go back, press the @key{<-} 
key.  
Pressing the @key{h} key 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 @key{p} key.  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 any other browser.

@node Translators, Troubleshooting, Networking, Top
@comment node, next, prev, up
@chapter Translators
@cindex translators
@cindex settrans
@cindex fsysopts
@cindex showtrans

The Hurd filesystem allows you to set translators on any file or
directory that you own.  A @dfn{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 GNU/Hurd.

Translators run with the privileges of the translated node's
@emph{owner}, so they cannot be used to compromise the security of the
system.  This also means that @emph{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:

@itemize @bullet
@item
Disk-based filesystem formats, such as @code{ext2fs}, @code{ufs}, and
@code{iso9660fs}.

@item
Network filesystems, such as @code{nfs} and @code{ftpfs}.

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

@item
@c FIXME: reword
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, @code{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 @code{file_name_lookup} (FIXME xref) on
@file{/servers/socket/1}@footnote{The number 1 corresponds to the
@code{PF_LOCAL} C library socket domain constant.}, then use Unix
socket-specific RPCs on that port, rather than adhering to the file
protocol.
@end itemize

This section focuses on the generic programs that must understand
in order to use existing translators.  The Hurd Hacking Guide and 
the GNU Hurd Reference Manual describe how you can write your own 
translators.

@menu
* Invoking settrans::           Declaring how a node should be translated.
* Invoking showtrans::          Displaying how nodes are translated.
* Invoking mount::              Unix-compatible active filesystem translators.
* Invoking fsysopts::           Modifying translation parameters at runtime.
@end menu


@node Invoking settrans, Invoking showtrans, Translators, Translators
@comment node, next, prev, up
@section Invoking @code{settrans}
@pindex settrans

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

The @code{settrans} program has the following synopsis:

@example
settrans [@var{option}]@dots{} @var{node} [@var{translator} @var{arg}@dots{}]
@end example

@noindent
where @var{translator} is the absolute filename of the new translator
program.  Each @var{arg} is passed to @var{translator} when it starts.
If @var{translator} is not specified, then @code{settrans} clears the
existing translator rather than setting a new one.

@code{settrans} accepts the following options:

@table @samp
@item -a
@itemx --active
Set @var{node}'s active translator.  @dfn{Active translators} are
started immediately and are not persistent: if the system is rebooted
then they are lost.

@item -c
@itemx --create
Create @var{node} as a zero-length file if it doesn't already exist.

@item -L
@itemx --dereference
If @var{node} is already translated, stack the new translator on top of
it (rather than replacing the existing translator).

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

@item -p
@itemx --passive
Set @var{node}'s passive translator.  @dfn{Passive translators} are only
activated by the underlying filesystem when clients try to use the
@var{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 @var{node} already has an
active translator, then the following options apply:

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

@table @samp
@item -f
@itemx --force
If the active translator doesn't go away, then force it.

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

@item -R
@itemx --recursive
Shut down all of the active translator's children, too.
@end table


@item -k
@itemx --keep-active
Leave the existing active translator running.  The new translator will
not be started unless the active translator has stopped.
@end table

@item -P
@itemx --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.

@item -t @var{sec}
@itemx --timeout=@var{sec}
If the translator does not start up in @var{sec} seconds (the default is
60), then return an error; if @var{sec} is 0, then never timeout.

@item --version
Output program version information and exit.

@item -x
@itemx --exclusive
Only set the translator if there is none already.
@end table


@node Invoking showtrans, Invoking mount, Invoking settrans, Translators
@comment node, next, prev, up
@section Invoking @code{showtrans}

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

The @code{showtrans} program has the following synopsis:

@example
showtrans [@var{option}]@dots{} @var{file}@dots{}
@end example

@code{showtrans} accepts the following options:

@table @code
@item -p
@itemx --prefix
Always display @var{filename}: before translators.

@item -P
@itemx --no-prefix
Never display @var{filename}: before translators.
@item -s
@itemx --silent
No output; useful when checking error status.
@item -t
@itemx --translated
Only display files that have translators.
@end table


@node Invoking mount, Invoking fsysopts, Invoking showtrans, Translators
@comment node, next, prev, up
@section Invoking @code{mount}


@node Invoking fsysopts,  , Invoking mount, Translators
@comment node, next, prev, up
@section Invoking @code{fsysopts}

The @code{fsysopts} program allows you to retrieve or set command line
options for running translator @var{filesys}.

The @code{fsysopts} program has the following synopsis:

@example
fsysopts [@var{option}@dots{}] @var{filesys} [@var{fs_option}@dots{}]
@end example

@code{fsysopts} accepts the following options:

@table @code

@item -L
@itemx --dereference
If @var{filesys} is a symbolic link, follow it.

@item -R
@itemx --recursive
Pass these options to any child translators.
@end table

The legal values for @var{fs_option} depends on @var{filesys}, but
some common ones are:

@table @code
@item --readonly
@item --writable
@item --remount
@item --sync[=@var{interval}]
@item --nosync
@end table

If no options are supplied, @var{filesys}' current options are
printed.

@node Troubleshooting, Finding More Information, Translators, Top
@comment node, next, prev, up
@chapter Troubleshooting
@cindex e2fsck
@cindex GRUB
@cindex fsysopts
@cindex ext2fs

In this chapter, we'll describe some basic troubleshooting steps to
recover from a system crash.  These sections are only the basics to
get you up and running in multi-user mode after a lock-up or some other
minor catastrophe.

@menu
* Fscking the filesystem::      Repairing your disk after a crash.    
* Booting and GRUB::           
@end menu

@c This is a start, we need to gather more info on this subject for 
@c newbies

@node Fscking the filesystem, Booting and GRUB , Troubleshooting, Troubleshooting
@comment node, next, prev, up
@section Fscking the filesystem

Occasionally, a mistake we make, or a bug in a program, causes
the machine to lock up. Usually, you have to shut the machine down with
the power button, or reset it.  Your filesystem on which GNU/Hurd resides
does not like this at all. GNU/Hurd uses the @command{e2fsck} tool to 
repair the damage done. When something happens, GNU/Hurd will invoke 
this at boot if the file system is marked unclean. 

Occasionally, the system cannot do this automatically, and you must repair 
the filesystem manually. First of all, you cannot repair a filesystem
that is read-only; you need the @command{fsysopt} command that we learned 
from the previous chapter. 

To begin, you must be in single-user mode.  If you boot your machine after 
a crash and the system cannot recover automatically, you will be in 
single-user mode by default after booting. At the prompt, enter the 
following commands (of course, substitute the device name of your 
root filesystem for @file{/dev/hd0s1}):

@display

 sh-2.05# fsysopts / --writable <ENTER>
 sh-2.05# e2fsck /dev/hd0s1 <ENTER>

@end display

The first command makes root filesystem writable, and the second runs 
the @kbd{e2fsck} program on the device where the filesystem resides. As 
this command runs, it will ask the user to repair certain things, always 
defaulting to YES. You should be able to just sit there and press 
@kbd{ENTER} until it tells you that the filesystem is clean.

You can then either type @kbd{reboot} and have a normal, clean 
startup, or you can type @kbd{exit} to leave single user mode and boot
into multi-user mode.

@node Booting and GRUB ,  , Fscking the filesystem, Troubleshooting
@comment node, next, prev, up
@section Booting and GRUB
@cindex Booting
@cindex GRUB

If your having problems getting your system to boot using the pre-made
Grub boot disk please take a look at this section.

@enumerate 
@item 
You should try and remember(and write down) where you installed GNU/Hurd
regardless of which method of installation you chose. For instance if
you installed from the CDs and the Hurd was placed on /dev/hda2 you need
to know that your Hurd install is on /dev/hd0s2

@item
You need to remember that Grub's root is one down from your installation
root whether your using GNU/Linux of GNU/Hurd. When I mention 
@emph{one down} I mean if you have a Hurd install on hd0s1 your 
Grub's root should be ``root (hd0,0)'' and if your Hurd's install is on 
hd0s2 your Grub's root should be ``root (hd0,1)''.

@item
You should remember that Grub ignores your cdrom drive. So if your
second harddrive is the primary drive on the second ide bus the Hurd
sees it as hd2s1 whereas Grub's root would be (hd1,0).. (Confusing
for us LiLO converts isn't it?)

@item
Most importantly you need to make sure the syntax is correct on your
module lines; Brackets, Spaces, Etc.  have thier meannings and cannot 
be interchanged. If your editor is a pain you can put a forward slash
to seperate the commands on seperate lines. This will still be seen
as one module line to Grub.For instance:
@display
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)
@end display

@item
If nothing is going your way you can try the out-dated serverboot method.
@display
root (hd0,0)
kernel /boot/gnumach.gz root=hd0s1
module /boot/serverboot.gz
@end display
Makeing sure you replace Grub and the Hurd's root with the appropriate
syntax.

@end enumerate
 

@node Finding More Information, Helping Out, Troubleshooting, Top
@comment node, next, prev, up
@chapter Finding More Information

@menu
* The info pages::              GNU's documentation.
* The man pages::               The traditional UNIX documentation.
* HOWTOs::                      Help on specific tasks.
* Websites of interest::        Websites supplying good Free documenation.
* Searching the web::           Searching the Internet for information.
* Mailing lists::               Getting help from other users.
@end menu

@node The info pages, The man pages, Finding More Information, Finding More Information
@comment node, next, prev, up
@section The info pages
@cindex info
@cindex GNU
@cindex Texinfo

The info pages contain complete manuals for GNU software.  The GNU Project 
uses Texinfo (@pxref{An Introduction to Texinfo}) to produce manuals as 
info pages, web pages, and printed documents.

An info file is simply a file on your machine.  To access an info file, you 
will need an info reader.  The default info reader is called @command{info}, 
others are @command{pinfo} and the GNOME Help Browser.  In our examples, we 
will assume that you are using @command{info}.

Info pages are hierarchally-structured documents.  Each info page consists 
of a set of nodes, which typically correspond to chapters and sections in a 
printed manual.  Each node contains pointers to other nodes, which behave 
similarly to hyperlinks on web pages.  Minimally, each node has three 
pointers: @emph{Next}, @emph{Prev} (Previous), and @emph{Up}.  Nodes may 
contain other pointers that are cross-references to other nodes.

If you are reading 
this manual as an info file, this node's name is ``The info pages,'' its 
@emph{Next} pointer points to ``The man pages,'' and its @emph{Prev} and 
@emph{Up} pointers both point to ``Finding More Information.''  In a 
printed version of this manual, ``Finding More Information'' is a chapter, 
and ``The info pages'' and ``The man pages'' are sections of that chapter.  
In addition, the first paragraph of this chapter contains a cross-reference 
to a node called ``An Introduction to Texinfo.''

Info pages show us how to use GNU software.  As an example, suppose that we 
have GNU Shogi @footnote{Shogi is the Japanese version of chess.} installed 
on our GNU system, and we want to know how to play it.  Typing 
@command{info gnushogi} at our command prompt, we are presented 
with the following:

@example
File: gnushogi.info,  Node: Top,  Next: (dir),  Prev: (dir),  Up: (dir)

GNU Shogi (Japanese chess)
**************************

* Menu:

* Introduction::         What is GNU shogi?
* License::              The GNU General Public License.
* About shogi::          General information, rules, etc.
* gnushogi::             How to play GNU shogi (gnushogi).
* xshogi::               The X interface to GNU shogi.
* References and links:: Where to go for more information.
* Acknowledgements::
* Bugs::                 Where and how to report bugs.
* Index::
@end example

This menu presents us with a list of pointers to nodes in the GNU Shogi 
manual.  If we move our cusor to, for example, the ``gnushogi::'' entry 
and press @key{Enter}, we will move to a new node of the GNU Shogi 
manual.

There are a few keys that you will use repeatedly when using @command{info}; 
for further information, type @command{info info} at your 
command prompt.

@itemize @bullet

@item
@key{n} : Follow this node's @emph{Next} pointer.

@item
@key{p} : Follow this node's @emph{Prev} pointer.

@item
@key{u} : Follow this node's @emph{Up} pointer.

@item
@key{l} : Return to the previously-visited node (like hitting ``Back'' in 
a web browser).

@item
@key{q} : Quit @command{info}.

@end itemize

@node The man pages, HOWTOs, The info pages, Finding More Information
@comment node, next, prev, up
@section The man pages
@cindex man
@cindex UNIX
@cindex man pages
The man pages, short for manual pages, are the traditional source of 
documentation for UNIX and 
UNIX-like systems.  In a UNIX system, each command, such as @command{cat} 
or @command{cp}, would have its own man page.  Manual pages would also exist 
for the system calls used by @emph{C} programmers, such as @command{mmap}.

As with the GNU system's info pages, man pages are files stored on your disk, 
and you need a man page reader in order to view them.  On GNU systems, the 
man page reader is called @command{man}.  To view, for example, the man 
page for @command{rm}, we would type @command{man rm} at our command 
prompt.

The man pages have several deficiencies when compared to the info pages; 
for example, 
they have no hyperlink-like mechanism for navigation, and often assume that 
the reader has a great deal of technical knowledge.  These, and other 
problems, make the man pages a poor source of documentation for beginners.  
Nevertheless, many GNU users who come from a UNIX background are very used 
to the man pages, so the man pages are available on GNU systems.

Since the man pages do not provide any hyperlink-like mechanism, we must find 
another way to search a long manual page for information.  The solution 
to this problem is the the @key{/} key.  Pressing @key{/} while viewing a 
manual page causes the @command{man} program to prompt us to enter a 
string, followed by the @key{Enter} key.  @command{man} will then jump to 
the first occurence of the string we enter, and highlight all occurences of 
the string.  Pressing @key{/} again, followed by @key{Enter}, will tell 
@command{man} to jump to the next occurence of the string.

The @key{/} key allows us to search within documents, but we still need a way 
to find out which man pages to consult on a particular topic.  The command 
that helps us do this is @command{apropos}.  For example, if we did not 
know the command for copying files, we would type @command{apropos copy}.  
The @command{apropos} program would then present us with a list of man 
pages for which ``copy'' is a keyword.

More information on the man pages can be obtained by typing @command{man man} 
or @command{man apropos} at your command prompt.

@node HOWTOs, Websites of interest, The man pages, Finding More Information
@comment node, next, prev, up
@section HOWTOs
@cindex HOWTOS
A HOWTO provides help on a specific subject, such as:

@itemize @bullet

@item Using software RAID
@item Printing
@item Programming @command{bash}
@item Using APT

@end itemize

You will find HOWTOs to be extremely useful.  A good example HOWTO that should 
be of interest to you is the @emph{APT HOWTO} at 
@uref{http://www.debian.org/doc/manuals/apt-howto/index.en.html}.

@node Websites of interest, Searching the web, HOWTOs, Finding More Information
@comment node, next, prev, up
@section Websites of Interest
@cindex www
@cindex on-line help

There are several websites that you will find extremely useful as you learn 
how to use Free UNIX-like systems such as GNU:

@itemize @bullet

@item @b{LinuxNewbie.org - @uref{http://www.linuxnewbie.org/}}: 
LinuxNewbie.org 
offers @emph{Newbieized Help Files (NHFs)}, which are like HOWTOs, but 
aimed specifically at beginners.  Despite the name, LinuxNewbie.org, most 
of the information provided is applicable to non-Linux-based GNU systems, and 
to *BSD systems also.

@item @b{The Linux Documentation Project - @uref{http://www.tldp.org/}}: 
@emph{The Linux Documentation Project} makes HOWTOs, in-depth guides, 
FAQs, and man pages.  In fact, many of the man pages available on GNU systems 
come from the Project.  As with LinuxNewbie.org, most 
of the Project's documentation is applicable to non-Linux-based GNU systems, 
and to *BSD systems also.

@item @b{Debian Documentation - @uref{http://www.debian.org/doc/}}: 
Debian provides manuals, HOWTOs, FAQs, and other documents with information 
specific to Debians distribution of GNU systems.

@item @b{Documentation of the GNU Project - 
@uref{http://www.gnu.org/doc/doc.html}}: Provides online versions of the 
GNU info pages, along with other Free Documentation.

@item @b{GNU's Hurd Page - @uref{http://www.gnu.org/software/hurd/}}: The 
official web site of the GNU Hurd.

@item @b{Debian GNU/Hurd - @uref{http://www.debian.org/ports/hurd/}}: 
Debian's GNU/Hurd web pages.

@item @b{The Hurd Wiki - @uref{http://hurd.gnufans.org/}}: A 
wiki is a forumn for online discussion and collaboration that is browsable 
as a web page.  To a user, it is essentially a web page that is editable by 
its users.  The Hurd Wiki is a wiki for GNU/Hurd, and it contains a wealth 
of insights by other GNU/Hurd users; it is an excellent resource.

@end itemize

@node Searching the web, Mailing lists, Websites of interest, Finding More Information
@comment node, next, prev, up
@section Searching the web
@cindex search
@cindex google
@cindex Mozilla
@cindex lynx

When we have a specific problem, and cannot easily find a solution in the 
documentation, searching the web will often help us solve our problem.  
Currently, the most popular search engine is @emph{Google}, available at 
@uref{http://www.google.com}.

We will present a real-life example.  Suppose that I am using the Galeon 
web browser on a Debian GNU system.  I visit @uref{http://www.google.com}

When we have a specific problem, and cannot easily find a solution in the 
documentation, searching the web will often help us solve our problem.  
Currently, the most popular search engine is @emph{Google}, available at 
@uref{http://www.google.com}.

We will present a real-life example.  Suppose that I am using the Mozilla 
web browser on a Debian GNU system, and I visit a web site that contains a 
Java applet, but Mozilla does not launch the applet.  To find out how to 
fix this problem, I visit Google:

@display
 sh-2.05$ lynx www.google.com @key{Enter}
@end display

Google presents me with a text box into which I can enter @emph{search terms}. 
 Into this text box, I type @emph{debian java mozilla}.  Google will then 
search the web for pages containing these three terms.  I look through 
the web pages that it gives me, and find one that tells me to make a 
symbolic link from Mozilla's plugin folder to the Java plugin provided 
by my Java installation:

@display
 # cd /usr/lib/mozilla/plugins @key{Enter}
 # ln -s /usr/j2sdk1.4.0_01/jre/plugin/i386/ns610/libjavaplugin_oji.so 
@key{Enter}
@end display

I then re-start Mozilla, and am able to use Java applets.

@node Mailing lists,  , Searching the web, Finding More Information
@comment node, next, prev, up
@section Mailing lists
@cindex mailing lists
@cindex email

Many free software projects offer mailing lists for support, inter-project 
communications, and significant announcements.  The mailing lists are 
essential sources of information.

Mailing lists for GNU/Hurd are served to us by the GNU Project.  The Debian 
GNU/Hurd port also has a mailing list hosted by the Debian Project.
New GNU/Hurd users have three mailing lists to help them on thier way: 
help-hurd@@gnu.org, bug-hurd@@gnu.org, and debian-hurd@@lists.debian.org.

@itemize @bullet

@item @b{help-hurd@@gnu.org} : This is the primary list for new users who 
need help installing, booting, and using GNU/Hurd.  If you are a programmer, 
this list is also the appropriate place to for help developing programs that 
use Hurd-specific features.

@item @b{debian-hurd@@lists.debian.org} : This list is used to communicate 
about issues regarding the Debian distribution (currently the only 
distribution) of GNU/Hurd. Much information is replicated on the 
help-hurd list.

@item @b{bug-hurd@@gnu.org} :  This is a list to report bugs and to see if 
you are experiencing some side effect of a bug.  Hurd developers also use 
this list to discuss the design and implementation of the Hurd servers.  If 
you subscribe to the Bug-Hurd list, you will receive many such emails.  Do 
not worry, users are not expected to understand all the technical details 
discussed on this list.

@end itemize

There are two other GNU/Hurd lists that will be of lesser interest to a new 
user: l4-hurd@@gnu.org, on which people discuss a planned port of the 
Hurd servers to the L4 microkernel, and web-hurd@@gnu.org, on which peopole 
discuss the Hurd's web pages.

You can sign up for the Help-Hurd, Bug-Hurd, and Debian GNU/Hurd mailing 
lists at the following URLs:
@itemize @bullet
@item @b{help-hurd@@gnu.org} : 
@uref{http://mail.gnu.org/mailman/listinfo/help-hurd}.
@item @b{debian-hurd@@lists.debian.org} : 
@uref{http://lists.debian.org/debian-hurd/}.
@item @b{bug-hurd@@gnu.org} : 
@uref{http://mail.gnu.org/mailman/listinfo/bug-hurd}.
@end itemize

Mailing list archives are kept for many years. If you search for some 
information on a topic, you might get data from years ago. This old 
information might be of some help to you, or it may be outdated. 
Mailing list archives are so heavily-used that 
a search on the web will give you many hits from different lists. To 
narrow things down, you need to find out where the list in question resides 
and search the server hosting the list. The lists mentioned above are 
currently archived at the following locations:
@itemize @bullet
@item @b{help-hurd@@gnu.org} : 
@uref{http://mail.gnu.org/archive/html/help-hurd/}.
@item @b{debian-hurd@@lists.debian.org} : 
@uref{http://lists.debian.org/debian-hurd/}.
@item @b{bug-hurd@@gnu.org} : 
@uref{http://mail.gnu.org/archive/html/bug-hurd/}.
@end itemize

Most hackers hate repeating publicly-available information.  
Before asking for help with a certain issue on a mailing list, 
a user should search the GNU/Hurd documentation and the mailing list archives 
for an answer to the question.  People who post to the Help-Hurd mailing
list asking questions that are answered in the Hurd FAQ, for example, 
will usually be ignored, or at least told to consult the relevant 
documentation.

Before leaving the subject of mailing lists, we should discuss the topic of 
mailing list etiquette.  We have already mentioned that it is impolite to 
ask questions that are answered in the documentation or the mailing list 
archives.  There are a number of rules of thumb that, if followed, will make 
your life much easier:

@itemize @bullet

@item @b{Be polite and respectful, and refrain from insulting others.} : This 
is a good rule of thumb in all social interactions, but it can be easy to 
forget when the other person is half-way across the world, and unable to 
give you a dirty look.  Now, if you follow the mailing lists for any free 
software project, you will notice people who violate this rule.  This 
behaviour may be tolerated if it comes from a great hacker, but it does not 
make the person more popular.

@item @b{Stay out of flame wars.} : A @dfn{flame war} is an emotional, and 
often irrational, argument between people who hold vastly different views 
on a subject.  Flame wars on mailing lists usually only annoy the list's 
subscribers, who have joined the list in hope of sharing @emph{useful} 
information.  There are people in this world who will get into flame wars 
on just about everything, from choice of kernel, to text editor, to 
desktop environment.  Ignore them.

@item @b{Respect the terminology and values of the GNU Project and Debian. } : 
Users of Debian GNU/Hurd are not in any way required to share the views of 
GNU or Debian; however, it is polite to realize that these projects have 
social goals, and to respect those goals while participating in disucssions 
on the mailing lists.  For example, promoting proprietary software on 
and GNU mailing lists is discouraged.  Similarly, it is in good taste to use 
the terminology used by the GNU and Debian projects; for example, say 
@dfn{GNU/Linux} when referring to the GNU system running on the Linux kernel, 
instead of referring to the entire system as simply @dfn{Linux}, and 
say @dfn{free software}, not @dfn{open source}.  Again, 
following this rule of thumb is not a requirement, but a courtesy which will 
make your life easier.

@item @b{Be prepared to help solve problems. } : If you report a problem on a 
mailing list, it is likely that you are not the only user experiencing that 
problem.  It is impolite to report your problem, but ask that no one reply 
to you.  GNU/Hurd users and developers want to fix problems in the GNU/Hurd 
system.  When reporting a new problem, you may be asked for more information, 
or asked to try different solutions to the problem.  In the next chapter, 
we will provide you with an introduction to the skills you will need in 
order to help track down the sources of these problems, and otherwise help 
contribute to the development of GNU/Hurd.

@end itemize

@node Helping Out, Copying, Finding More Information, Top
@comment node, next, prev, up
@chapter Helping Out
@cindex contribute

In this chapter, we'll be describing the basic skills you need in order 
to help develop the GNU system. You do not need to be a hot-shot 
programmer capable of writing incredibly-obscure code to help with 
GNU's development; users willing to test the system for bugs and 
suggest improvements are valuable, as are writers of documentation, 
promoters, and others.

Although this chapter is intended to give you an introduction to the 
skills you will need in order to help develop GNU, much of this material 
will also be of interest to users who want to tweak their system, and 
compile bleeding-edge programs.@footnote{``Bleeding-edge'' is a pun 
on ``leading-edge''; leading-edge products often have had very little 
testing, and may contain serious bugs.}

@menu
* Basic CVS Usage::             Getting development files.
* Using gcc::                   Compiling programs.
* Makefiles::                   Compiling big programs.
* An Introduction to Texinfo::  GNU's documentation format.
* Debugging with GDB::          Using the GNU debugger.
* Reporting Bugs::              How to report problems.
@end menu

@node Basic CVS Usage, Using gcc, Helping Out, Helping Out
@comment node, next, prev, up
@section Basic CVS Usage
@cindex CVS
@cindex Repository
@cindex module
@cindex pserver
Web pages for Free Software often state something along the lines of, ``The 
source for this program is available through CVS.'' A reasonable question 
upon seeing this statement is, ``What the heck is CVS?''

CVS stands for Concurrent Versions Systems. It is a very important tool for 
Free Software developers. CVS stores the files in a project in a centralized 
location called the @emph{Repository}, which will usually be connected to 
a server. @footnote{In general, the term @emph{server} refers to a program 
or a computer that provides a service to others; in this case, the server 
is a computer connected to the Internet, coupled with software that allows 
people store and retreive files through CVS.} 

In the GNU system, we access CVS repositories using a program called 
@command{cvs}. Your first introduction to CVS will probably be getting files 
for a bleeding-edge program using @emph{anonymous CVS}. This means that you 
will contact a CVS server, tell it that you are an anoymous user, and ask it 
for the files you want. When using anonymous CVS, you typically have 
permission to get files, but no permission to store files in the Repository.

As an example, let's look at some example CVS commands from the 
@emph{Hurd Hacking Guide}:

@display

#!/bin/sh

cd $HOME
mkdir hurd-cvs
cd hurd-cvs/

# Use the empty string password:
cvs -d:pserver:anoncvs@@subversions.gnu.org:/cvsroot/hurd login

for module in hurd gnumach
do
  cvs -z3 -d:pserver:anoncvs@@subversions.gnu.org:/cvsroot/hurd \
      co $module
done

@end display

This simple shell script makes a directory in our home directory called 
@file{hurd-cvs}, and places the source code for GNU Mach and the Hurd 
in that directory.

We'll translate these @command{cvs} commands into English to help you get 
started with CVS. As the CVS manual (available on the GNU system through
@command{info cvs}) states, the structure of CVS commands is:

@display
cvs [ cvs_options ] cvs_command [ command_options ] [ command_args ]
@end display

@code{login} and @code{co} (checkout) are both @code{cvs_command}s. So, 
our @code{cvs_options} in the above commands are 
@code{-d:pserver:anoncvs@@subversions.gnu.org:/cvsroot/hurd}, for both 
commands, and @code{-z3} for the second command.

@code{-z3} is simple to understand: it specifies the level of compression of 
the files we're checking out. In this case, the files have been compressed 
at compression level three.

@code{-d:pserver:anoncvs@@subversions.gnu.org:/cvsroot/hurd} is slightly more 
complicated. The @code{-d} stands for @emph{directory}; it tells @command{cvs} 
that the remainder of this string specifies the location with which we are 
communicating. @code{:pserver:} stands for @emph{password-authenticated 
server}; @code{subversions.gnu.org} is a server that uses passwords to 
authenticate its users. @file{/cvsroot/hurd} is a directory on 
@code{subversions.gnu.org}. So, the whole string says, ``I want to interact 
with a password-authenticated server called 
@code{anoncvs@@subversions.gnu.org}, and the files that interest me are 
in a directory on it called @file{/cvsroot/hurd}.''

This should give you a basic idea of what CVS is. Don't be intimidated by it; 
although its syntax may seem cryptic, you will probably not need to use the 
full range of its abilities, and what you do need to know can be easily 
learned when you need it.

More advanced CVS usage is beyond the scope of this document; however, 
the CVS manual is quite good and can be accessed locally by typing 
@code{info cvs} in your shell on any GNU system. The manual is also 
available online at @uref{http://www.gnu.org/manual/cvs/index.html}.

@node Using gcc, Makefiles, Basic CVS Usage, Helping Out
@comment node, next, prev, up
@section Using gcc
@cindex gcc
@cindex hello.c
@cindex compiled

GCC stands for ``GNU Compiler Collection.'' The acronym originally stood for 
``GNU C Compiler.'' GCC is one of the cornerstones of Free Software.

GCC is a @dfn{compiler}: a program that takes as input a file in a high-level 
computer language, and produces a set of machine-readable instructions that 
form an executable program. The input file is called the @dfn{source code}; 
the availablility of this code to all for modification and improvement is 
a hallmark of the Free Software and Open Source movements.

To see how compilers such as GCC work, we will use a common example program 
called @emph{Hello World}. Any book that describles a computer language 
begins by showing a variation of this program written in that language, since 
it shows the minimum functionality required to let the user know that the 
program has been run. Our version of Hello World is written in @dfn{C}, the 
language in which GNU Mach and the Hurd servers are written.

Type the following text into your favourite text editor:

@example
#include <stdio.h>

int 
main()
@{
  printf(``Hello, Welcome to the GNU/Hurd Community!\n'');
  return 0;
@}
@end example

We will not delve into the meaning of this code, as a discussion of @emph{C} 
is beyond the scope of this book. There are, however, many excellent books 
on @emph{C} available; the official @emph{GNU C Programming Tutorial} is 
available at @uref{http://savannah.gnu.org/projects/ctut-mb-rwhe/}.

Save this file as @file{hello.c}. Then, type the following command at your 
command prompt:

@display

 sh-2.05$ gcc hello.c @key{<ENTER>}

@end display

The command @command{gcc} invokes gcc. @command{gcc} will create an 
executable program called, by default, @file{a.out}. Now, at your command 
prompt, type:

@display

 sh-2.05$ ./a.out @key{<ENTER>}

@end display

You should see the text ``Hello, Welcome to the GNU/Hurd Community!'' appear 
on your screen.

Congratulations! You have just compiled a program.

The @command{gcc} program has many options that are useful to programmers. 
Whether you are a programmer or not, this basic knowledge of compilers will 
help you understand your GNU System.

To learn more about GCC, type @code{info gcc} at your command 
prompt.

@node Makefiles, An Introduction to Texinfo, Using gcc, Helping Out
@comment node, next, prev, up
@section Makefiles
@cindex make

In the previous section, we describled the use of @command{gcc}, the GNU 
System's compiler. You may have guessed that building complex software 
packages such as the Hurd using only @command{gcc} is much too difficult a 
task for the average end-user. Acutally, even developers would find such a 
task extremely complex.

To alleviate this difficulty, we introduce @dfn{makefiles}. Makefiles are 
used by the GNU System, as well as many other systems, as a way of automating 
the process of building programs.

@node An Introduction to Texinfo, Debugging with GDB, Makefiles, Helping Out
@comment node, next, prev, up
@section An Introduction to Texinfo
@cindex texinfo

The Texinfo documentation language was invented by Richard M. Stallman.
He devised the system from a MIT project called Bolio (combined with @TeX{}
to form Bo@TeX{}) and a CMU project called Scribe.   Robert J. Chassell, 
Brian Fox, and Karl Berry have also helped developed Texinfo into
the mature, robust, and well-documented format we have today.

The purpose of Texinfo is to be able to create one document that can
be transfered to another document format.  A user can make a document
that can be viewed in a terminal's info viewer, a web browser, or 
as a Postscript, PDF, or DVI file.  The latter formats can be printed 
to product hard-copies of GNU manuals.

The Texinfo syntax has many @@ symbols. These @@ symbols
precede Texinfo commands that manipulate the text. The greatest thing 
about the official GNU documentation format is that
it is well-documented.  The Texinfo manual can be invoked with the
command @command{info texinfo}.  The Texinfo manual has sample documents,
tips, suggestions, and tutorials (the Emacs text editor works great 
with Texinfo and is covered in the manual).

Some readers may have had previous experience with @TeX{} or La@TeX{}, the 
latter of which is used for most mathematical typesetting.  If you 
have used either of these typesetting languages, you will notice that 
Texinfo has a similar flavour, which is different from the languages 
in the SGML/HTML/XML family.  Texinfo is quite easy to learn, however, 
and is an excellent tool for producing documentation.

@c structure of Info documents, why @TeX{}/Texinfo is good, etc.

@c More complete information on using @command{info} is available by typin@c g 
@c @command{info info} at your shell prompt.  Typing @command{info texinfo@c } 
@c will give you access to the complete Texinfo manual.

@node Debugging with GDB, Reporting Bugs, An Introduction to Texinfo, Helping Out
@c node, next, prev, up
@section Debugging with GDB
@cindex debugging

A @dfn{bug} is any problem with a program that results in the program 
crashing, or otherwise behaving incorrectly.  If you follow the 
mailing lists of any software project, you will see people discuss bugs, 
and how to fix them.

Finding and fixing bugs in programs is primarily the responsibility of the 
programs' developers.  Bugs, however, can be devious, and may only show 
up under certain conditions.  Sometimes, these conditions do not occur 
on any developer's system, and the users of a program are the first to 
find a bug.  An advantage of Free Software is that when users with 
programming skills find bugs, they can often fix the bugs themselves, and 
send the fixes to the project's core developers.  Even when users cannot 
fix the bug in question themselves, they can often find the cause of the 
bug, enabling the project developers to fix the bug more quickly.

A @dfn{debugger} is a program that helps you debug another program.  The 
GNU debugger is called GDB, and is invoked using the @command{gdb} 
command. 

We will introduce you to GDB with a small example; for more complete 
documentation, consult the GDB manual (available, of course, by typing 
@command{info gdb} at the command prompt of any GNU system).  

In this section, we assume that you are familiar with the @emph{C} programming 
language.  Consider the following small @emph{C} program, which accepts a 
list of numbers on the command line, and outputs their sum:

@example
/* sum.c
 *
 * Outputs the sum of the numbers entered on the command line.
 */

#include<stdio.h>

int 
sum(int n, int index, char** vector)
@{
  if (index == n)
    return 0;
  else
    return atoi(vector[index]) + sum(n,index++,vector);
@}

int
main(int argc, char* argv[])
@{
  printf("sum is %d\n", sum(argc,1,argv));
  return 0;
@}
@end example

Observe that we have implemented the @code{sum()} function as a recursive 
function.  We could have implemented @code{sum()} iteritavely, but this 
implementation is useful for our example.

Also note that we add the contents of the argument vector (@code{argv}) 
starting at position 1; this is because @code{argv[0]} contains the name 
of the program, and @code{argv[1]} through @code{argv[argc-1]} are the 
actual command-line arguments.

We can compile this program using @command{gcc} and run it:

@display
$ gcc -o sum sum.c @key{ENTER}
$ ./sum 1 2 3 4 5 @key{ENTER}
$ 
@end display

Running this program on my system produces no output (hence the prompt on 
the next line).  The program should, however, print ``sum is 15''.

We can use GDB to find the cause of this problem.  To help 
GDB do its job, we will recompile our program with 
@emph{debugging symbols}, which will provide GDB with extra 
information.  We do this by passing the @command{-g} option to @command{gcc}:

@display
$ gcc -g -o sum sum.c @key{ENTER}
@end display

To debug this program using GDB, we type:

@display
$ gdb sum @key{ENTER}
GNU gdb 2002-12-19-cvs (cygwin-special)
Copyright 2002 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and 
you are welcome to change it and/or distribute copies of it under 
certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB.  Type "show warranty" 
for details.
This GDB was configured as "i686-pc-cygwin"...
(gdb)
@end display

We are given a @emph{(gdb)} prompt for running @command{gdb} commands.  
GDB includes a builting command, @command{help}, that provides help on 
GDB commands.  Typing @command{help} on its own causes GDB to print a 
list of commands, while typing @command{help command} produces help on the 
command @command{command}.

The first command we will use is the @command{list} command, which shows 
us the part of the code for the program we are debugging (this is some 
of the information we get by compiling with debugging symbols):

@display
(gdb) list @key{ENTER}
11        if (index == n)
12          return 0;
13        else
14          return atoi(vector[index]) + sum(n,index++,vector);
15      @}
16
17      int
18      main(int argc, char* argv[])
19      @{
20        printf("sum is %d\n", sum(argc,1,argv));
(gdb)
@end display

Notice that each line of the program source starts with a number.  These 
numbers are important, since they are one of the means by which we tell GDB to 
examine different parts of the program.  For example, we can type 
@command{list 1} to have GDB list the program source around line 1. Line 
numbers, however, are not the only means by which we can refer to parts of our 
program; we can also type @command{list sum} to have GDB list the program 
source around the beginning of the @code{sum()} function.

Now, on to the actual debugging.  We can examine the @code{main()} function, 
and observe that its contents are fairly trivial; we thus guess that the 
error must be in our @code{sum()} function.  We can set a @dfn{breakpoint} 
at the beginning of the sum function like so:

@display
(gdb) break sum @key{ENTER}
Breakpoint 1 at 0x401097: file sum.c, line 11.
(gdb)
@end display

We can then insturct GDB to begin running our program with the inputs 1, 2, 3, 
4, and 5:

@display
(gdb) run 1 2 3 4 5 @key{ENTER}
@end display

GDB stops when it hits the breakpoint we set:

@display
Breakpoint 1, sum (n=6, index=1, vector=0xa041eb0) at sum.c:11
11        if (index == n)
(gdb) 
@end display

This seems all right.  We tell GDB to continue execution:

@display
(gdb) continue @key{ENTER}
@end display

GDB stops the next time we hit our breakpoint:

@display
Breakpoint 1, sum (n=6, index=1, vector=0xa041eb0) at sum.c:11
11        if (index == n)
(gdb) 
@end display

Now @emph{that} is odd.  The value of @code{index} is unchanged, but it 
should have been incremented.  As a sanity check, we can tell GDB explicitly 
to print out the value of @code{index}:

@display
(gdb) print index @key{ENTER}
$1 = 1
(gdb)
@end display

As expected, @code{index} is still 1.  We tell GDB to go to the next line 
of code:

@display
(gdb) next @key{ENTER}
14          return atoi(vector[index]) + sum(n,index++,vector);
(gdb)
@end display

That is normal.  We continue to the next line of code:

@display
(gdb) next @key{ENTER}

Breakpoint 1, sum (n=6, index=0, vector=0xa041eb0) at sum.c:11
11        if (index == n)
@end display

We are back at our breakpoint, and, again, index is unchanged.

GDB has been very helpful, and we now must use another debugging tool - our 
minds - to complete the job.  We know that @code{index} is not being 
incremented, and that the only line of code in our problem area that should 
modify @code{index} is:

@display
14          return atoi(vector[index]) + sum(n,index++,vector);
@end display

We then see our little mistake.  In our function call 
@code{sum(n,index++,vector)}, our use of @code{index++} causes index 
to be incremented @emph{after} the call to @code{sum()}.  Hence, we use the 
same value of @code{index} at each invocation of @code{sum()}.

In theory, this creates infinite recursion; however, since each call to 
@code{sum()} requires the use of a stack frame, we quickly run out of space 
on the stack, causing the program to crash.  We can see the exact error 
message by clearing the breakpoint in our program, and telling GDB 
to continue execution:

@display
(gdb) clear sum @key{ENTER}
Deleted breakpoint 1
(gdb) continue @key{ENTER}
Continuing.

Program received signal SIGSEGV, Segmentation fault.
0x610ac933 in _libkernel32_a_iname ()
(gdb)
@end display

To finish our debugging session, we use the @command{finish} command to 
stop the program being debugged, and the @command{quit} command to 
quit GDB:

@display
(gdb) finish @key{ENTER}
Run till exit from #0  0x610ac933 in _libkernel32_a_iname ()
Warning:
Cannot insert breakpoint 0.
Error accessing memory address 0x0: I/O error.

(gdb) quit @key{ENTER}
@end display

We can fix our program by changing @code{index++} to @code{++index}, so that 
the value of @code{index} is incremented @emph{before} the call to 
@code{sum()}.  We then recompile the program, and run it again:

@display
$ ./sum 1 2 3 4 5
sum is 15
$
@end display

The program now works correctly.

In our example, we have only scratched the surface of what GDB can do.  We 
can also @emph{attach} gdb to a process that is already running, using 
GDB's @command{attach} command; this is often necessary when debugging 
the Hurd servers.  To learn all the details of using GDB, consult the 
GDB manual - again, this is accessible via the command @command{info gdb}.

@node Reporting Bugs,  , Debugging with GDB, Helping Out
@comment node, next, prev, up
@section Reporting Bugs
@cindex BTS
when to use bug-hurd versus Debian BTS, how to file a *good* bug report

@node Copying, Index, Helping Out, Top
@comment node, next, prev, up
@chapter Copying
@cindex GPL
The GNU Hurd and this manual are distributed under the terms of the GNU 
General Public License.  The GNU @dfn{GPL} protects your right to 
use, modify, and distribute all parts of the GNU system.

@menu
* GNU General Public License::  Protecting your rights.
@end menu

@node GNU General Public License,  , Copying, Copying
@comment node, next, prev, up
@section GNU General Public License

@include gpl.texinfo

@node Index,  , Copying, Top
@unnumbered Index

@printindex cp

@summarycontents
@contents
@bye



Send suggestions and report system problems to the Savannah Hackers.
ViewVC Help
Powered by ViewVC 1.0.7