os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Huge whitespace changes. Translators can ignore this commit completely.

Browse source 
Rationale: All the changes to the DocBook handbook so far have been
careful to keep whitespace changes to a minimum. This is so the
translators have as easy a job as possible in identifying exactly what's
changed.

This has meant the English version has become more and more 'ugly'. Lines
indented by the wrong amount, some lines longer than 130 characters,
others shorter than 20, gaps of 3 or 4 lines between paragraphs (and
sometimes within paragraphs). This makes it difficult to follow the
structure of the document, and needlessly complicates fixing SGML
problems.

It also makes the source practically useless as a teaching aid; the
more baroque the source looks, the less likely people are to dive in and
contribute.

This commit fixes all that -- and boy was it tedious. The snag is, it's
touched almost every line in every file in the Handbook.

Technically, the changes were made by running (in Emacs)
sgml-indent-or-tab (bound to the TAB key) on almost each line (except
those in <programlisting>, <screen>, <literallayout>, and other
verbatim sections), and then running sgml-fill-element (bound to
C-c C-q) on most paragraphs.

FWIW, this is the first, only, and last change of this type contemplated.
This commit is contained in:
Nik Clayton 1999-03-07 21:26:43 +00:00
parent 62a7d13816
commit 1e28ab5a96
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=4472
93 changed files with 123203 additions and 116140 deletions
Download patch file Download diff file Expand all files Collapse all files

835
en/handbook/advanced-networking/chapter.sgml
View file

File diff suppressed because it is too large Load diff

265
en/handbook/backups/chapter.sgml
View file

@ -9,10 +9,10 @@
impossible to provide a exhaustive listing of hardware that FreeBSD
supports, this section serves as a catalog of the device drivers included
with FreeBSD and the hardware each drivers supports. Where possible and
appropriate, notes about specific products are included. You may also want
to refer to <link linkend="kernelconfig-config"> the kernel configuration
file</link> section in this handbook for a list of supported
devices.</para>
appropriate, notes about specific products are included. You may also
want to refer to <link linkend="kernelconfig-config"> the kernel
configuration file</link> section in this handbook for a list of
supported devices.</para>
<para>As FreeBSD is a volunteer project without a funded testing department,
we depend on you, the user, for much of the information contained in this
@ -37,8 +37,7 @@
DLT.</para>
<sect2 id="backups-tapebackups-4mm">
<title>4mm (DDS: Digital Data
Storage)</title>
<title>4mm (DDS: Digital Data Storage)</title>
<para>4mm tapes are replacing QIC as the workstation backup media of
choice. This trend accelerated greatly when Conner purchased Archive,
@ -52,9 +51,9 @@
<para>Data thruput on these drives starts ~150kB/s, peaking at ~500kB/s.
Data capacity starts at 1.3 GB and ends at 2.0 GB. Hardware
compression, available with most of these drives, approximately
doubles the capacity. Multi-drive tape library units can have 6 drives
in a single cabinet with automatic tape changing. Library capacities
reach 240 GB.</para>
doubles the capacity. Multi-drive tape library units can have 6
drives in a single cabinet with automatic tape changing. Library
capacities reach 240 GB.</para>
<para>4mm drives, like 8mm drives, use helical-scan. All the benefits
and drawbacks of helical-scan apply to both 4mm and 8mm drives.</para>
@ -73,19 +72,19 @@
One downside of 8mm tape is relatively short head and tape life due to
the high rate of relative motion of the tape across the heads.</para>
<para>Data thruput ranges from ~250kB/s to ~500kB/s. Data sizes start at
300 MB and go up to 7 GB. Hardware compression, available with most of
these drives, approximately doubles the capacity. These drives are
available as single units or multi-drive tape libraries with 6 drives
and 120 tapes in a single cabinet. Tapes are changed automatically by
the unit. Library capacities reach 840+ GB.</para>
<para>Data thruput ranges from ~250kB/s to ~500kB/s. Data sizes start
at 300 MB and go up to 7 GB. Hardware compression, available with
most of these drives, approximately doubles the capacity. These
drives are available as single units or multi-drive tape libraries
with 6 drives and 120 tapes in a single cabinet. Tapes are changed
automatically by the unit. Library capacities reach 840+ GB.</para>
<para>Data is recorded onto the tape using helical-scan, the heads are
positioned at an angle to the media (approximately 6 degrees). The
tape wraps around 270 degrees of the spool that holds the heads. The
spool spins while the tape slides over the spool. The result is a high
density of data and closely packed tracks that angle across the tape
from one edge to the other.</para>
spool spins while the tape slides over the spool. The result is a
high density of data and closely packed tracks that angle across the
tape from one edge to the other.</para>
</sect2>
<sect2 id="backups-tapebackups-qic">
@ -100,21 +99,22 @@
<emphasis>most</emphasis> common tape drive. Every site has a QIC
drive of some density or another. Therein lies the rub, QIC has a
large number of densities on physically similar (sometimes identical)
tapes. QIC drives are not quiet. These drives audibly seek before they
begin to record data and are clearly audible whenever reading, writing
or seeking. QIC tapes measure (6 x 4 x 0.7 inches; 15.2 x 10.2 x 1.7
mm). <link linkend="backups-tapebackups-mini">Mini-cartridges</link>,
which also use 1/4" wide tape are discussed separately. Tape libraries
and changers are not available.</para>
tapes. QIC drives are not quiet. These drives audibly seek before
they begin to record data and are clearly audible whenever reading,
writing or seeking. QIC tapes measure (6 x 4 x 0.7 inches; 15.2 x
10.2 x 1.7 mm). <link
linkend="backups-tapebackups-mini">Mini-cartridges</link>, which
also use 1/4" wide tape are discussed separately. Tape libraries and
changers are not available.</para>
<para>Data thruput ranges from ~150kB/s to ~500kB/s. Data capacity
ranges from 40 MB to 15 GB. Hardware compression is available on many
of the newer QIC drives. QIC drives are less frequently installed;
they are being supplanted by DAT drives.</para>
<para>Data is recorded onto the tape in tracks. The tracks run along the
long axis of the tape media from one end to the other. The number of
tracks, and therefore the width of a track, varies with the tape's
<para>Data is recorded onto the tape in tracks. The tracks run along
the long axis of the tape media from one end to the other. The number
of tracks, and therefore the width of a track, varies with the tape's
capacity. Most if not all newer drives provide backward-compatibility
at least for reading (but often also for writing). QIC has a good
reputation regarding the safety of the data (the mechanics are simpler
@ -160,15 +160,13 @@
<sect2>
<title>Using a new tape for the first time</title>
<para>The first time that you try to read or write a new,
completely blank tape, the operation will fail. The console
messages should be similar to:</para>
<para>The first time that you try to read or write a new, completely
blank tape, the operation will fail. The console messages should be
similar to:</para>
<screen>st0(ncr1:4:0): NOT READY asc:4,1
st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
<para>The tape does not contain an Identifier Block (block number 0).
All QIC tape drives since the adoption of QIC-525 standard write an
Identifier Block to the tape. There are two solutions:</para>
@ -178,12 +176,11 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
<para>Use the front panel button to eject the tape.</para>
<para>Re-insert the tape and
&man.dump.8; data to the tape.</para>
<para>Re-insert the tape and &man.dump.8; data to the tape.</para>
<para>&man.dump.8; will report <literal>DUMP:
End of tape detected</literal> and the console will show:
<literal>HARDWARE FAILURE info:280 asc:80,96</literal></para>
<para>&man.dump.8; will report <literal>DUMP: End of tape
detected</literal> and the console will show: <literal>HARDWARE
FAILURE info:280 asc:80,96</literal></para>
<para>rewind the tape using: <command>mt rewind</command></para>
@ -203,84 +200,81 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
<sect2>
<title>Dump and Restore</title>
<para>&man.dump.8; and &man.restore.8; are the traditional Unix backup programs. They operate
on the drive as a collection of disk blocks, below the abstractions of
files, links and directories that are created by the filesystems.
&man.dump.8; backs up devices, entire filesystems, not parts of a
filesystem and not directory trees that span more than one filesystem,
using either soft links &man.ln.1; or mounting one filesystem onto another.
&man.dump.8; does not write files and directories to tape, but
rather writes the data blocks that are the building blocks of files
and directories. &man.dump.8; has quirks that remain from its early days in
Version 6 of ATT Unix (circa 1975). The default parameters are
suitable for 9-track tapes (6250 bpi), not the high-density media
available today (up to 62,182 ftpi). These defaults must be overridden
on the command line to utilize the capacity of current tape
drives.</para>
<para>&man.dump.8; and &man.restore.8; are the traditional Unix backup
programs. They operate on the drive as a collection of disk blocks,
below the abstractions of files, links and directories that are
created by the filesystems. &man.dump.8; backs up devices, entire
filesystems, not parts of a filesystem and not directory trees that
span more than one filesystem, using either soft links &man.ln.1; or
mounting one filesystem onto another. &man.dump.8; does not write
files and directories to tape, but rather writes the data blocks that
are the building blocks of files and directories. &man.dump.8; has
quirks that remain from its early days in Version 6 of ATT Unix (circa
1975). The default parameters are suitable for 9-track tapes (6250
bpi), not the high-density media available today (up to 62,182 ftpi).
These defaults must be overridden on the command line to utilize the
capacity of current tape drives.</para>
<para>&man.rdump.8; and &man.rrestore.8; backup data across the
network to a tape drive attached to another computer. Both programs
rely upon &man.rcmd.3; and &man.ruserok.3; to access the remote tape
drive. Therefore, the user performing the backup must have
<para>&man.rdump.8; and &man.rrestore.8; backup data across the network
to a tape drive attached to another computer. Both programs rely upon
&man.rcmd.3; and &man.ruserok.3; to access the remote tape drive.
Therefore, the user performing the backup must have
<literal>rhosts</literal> access to the remote computer. The
arguments to &man.rdump.8; and &man.rrestore.8; must suitable to use on the remote computer. (e.g.
When <command>rdump</command>'ing from a FreeBSD computer to an
Exabyte tape drive connected to a Sun called
<hostid>komodo</hostid>, use: <command>/sbin/rdump 0dsbfu 54000
13000 126 komodo:/dev/nrst8 /dev/rsd0a 2>&amp;1</command>) Beware:
there are security implications to allowing <literal>rhosts</literal>
arguments to &man.rdump.8; and &man.rrestore.8; must suitable to use
on the remote computer. (e.g. When <command>rdump</command>'ing from
a FreeBSD computer to an Exabyte tape drive connected to a Sun called
<hostid>komodo</hostid>, use: <command>/sbin/rdump 0dsbfu 54000 13000
126 komodo:/dev/nrst8 /dev/rsd0a 2>&amp;1</command>) Beware: there
are security implications to allowing <literal>rhosts</literal>
commands. Evaluate your situation carefully.</para>
</sect2>
<sect2>
<title>Tar</title>
<para>&man.tar.1; also dates back to Version 6 of ATT Unix (circa
1975). &man.tar.1; operates in cooperation with the filesystem;
&man.tar.1; writes files and directories to tape.
&man.tar.1; does not support the full range of options that are
available from &man.cpio.1;, but &man.tar.1; does not require the
unusual command pipeline that &man.cpio.1; uses.</para>
<para>&man.tar.1; also dates back to Version 6 of ATT Unix (circa 1975).
&man.tar.1; operates in cooperation with the filesystem; &man.tar.1;
writes files and directories to tape. &man.tar.1; does not support the
full range of options that are available from &man.cpio.1;, but
&man.tar.1; does not require the unusual command pipeline that
&man.cpio.1; uses.</para>
<para>Most versions of &man.tar.1; do not support backups across the network. The GNU
version of &man.tar.1;, which FreeBSD utilizes,
supports remote devices using the same syntax as
&man.rdump.8;. To &man.tar.1; to an Exabyte tape drive connected to a Sun called
<hostid>komodo</hostid>, use: <command>/usr/bin/tar cf komodo:/dev/nrst8 .
2>&amp;1</command>. For versions without remote device support,
you can use a pipeline and &man.rsh.1; to send the data to a
remote tape drive. (XXX add an example command)</para>
<para>Most versions of &man.tar.1; do not support backups across the
network. The GNU version of &man.tar.1;, which FreeBSD utilizes,
supports remote devices using the same syntax as &man.rdump.8;. To
&man.tar.1; to an Exabyte tape drive connected to a Sun called
<hostid>komodo</hostid>, use: <command>/usr/bin/tar cf
komodo:/dev/nrst8 . 2>&amp;1</command>. For versions without remote
device support, you can use a pipeline and &man.rsh.1; to send the
data to a remote tape drive. (XXX add an example command)</para>
</sect2>
<sect2>
<title>Cpio</title>
<para>&man.cpio.1; is the original Unix
file interchange tape program for magnetic media. &man.cpio.1; has options (among many
others) to perform byte-swapping, write a number of different
archives format, and pipe the data to other programs. This last
feature makes &man.cpio.1; and excellent choice for
installation media. &man.cpio.1; does not know how to walk
the directory tree and a list of files must be provided thru
<filename>STDIN</filename>.</para>
<para>&man.cpio.1; is the original Unix file interchange tape program
for magnetic media. &man.cpio.1; has options (among many others) to
perform byte-swapping, write a number of different archives format,
and pipe the data to other programs. This last feature makes
&man.cpio.1; and excellent choice for installation media.
&man.cpio.1; does not know how to walk the directory tree and a list
of files must be provided thru <filename>STDIN</filename>.</para>
<para>&man.cpio.1; does not support backups
across the network. You can use a pipeline and &man.rsh.1; to send the data to a
remote tape drive. (XXX add an example command)</para>
<para>&man.cpio.1; does not support backups across the network. You can
use a pipeline and &man.rsh.1; to send the data to a remote tape
drive. (XXX add an example command)</para>
</sect2>
<sect2>
<title>Pax</title>
<para>&man.pax.1; is IEEE/POSIX's answer to
&man.tar.1; and &man.cpio.1;. Over the years the
various versions of &man.tar.1; and &man.cpio.1;
have gotten slightly incompatible. So rather than fight it out to
fully standardize them, POSIX created a new archive utility.
&man.pax.1; attempts to read and write many of the various
&man.cpio.1; and &man.tar.1; formats, plus new formats of its own. Its command set
more resembles &man.cpio.1; than
&man.tar.1;.</para>
<para>&man.pax.1; is IEEE/POSIX's answer to &man.tar.1; and
&man.cpio.1;. Over the years the various versions of &man.tar.1;
and &man.cpio.1; have gotten slightly incompatible. So rather than
fight it out to fully standardize them, POSIX created a new archive
utility. &man.pax.1; attempts to read and write many of the various
&man.cpio.1; and &man.tar.1; formats, plus new formats of its own.
Its command set more resembles &man.cpio.1; than &man.tar.1;.</para>
</sect2>
<sect2 id="backups-programs-amanda">
@ -290,9 +284,9 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
(Advanced Maryland Network Disk Archiver) is a client/server backup
system, rather than a single program. An Amanda server will backup to
a single tape drive any number of computers that have Amanda clients
and network communications with the Amanda server. A common problem at
locations with a number of large disks is the length of time required
to backup to data directly to tape exceeds the amount of time
and network communications with the Amanda server. A common problem
at locations with a number of large disks is the length of time
required to backup to data directly to tape exceeds the amount of time
available for the task. Amanda solves this problem. Amanda can use a
"holding disk" to backup several filesystems at the same time. Amanda
creates "archive sets": a group of tapes used over a period of time to
@ -312,9 +306,9 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
<title>Do nothing</title>
<para>&ldquo;Do nothing&rdquo; is not a computer program, but it is the
most widely used backup strategy. There are no initial costs. There is
no backup schedule to follow. Just say no. If something happens to
your data, grin and bear it!</para>
most widely used backup strategy. There are no initial costs. There
is no backup schedule to follow. Just say no. If something happens
to your data, grin and bear it!</para>
<para>If your time and your data is worth little to nothing, then
&ldquo;Do nothing&rdquo; is the most suitable backup program for your
@ -334,19 +328,20 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
<sect2>
<title>Which Backup Program is Best?</title>
<para>&man.dump.8; <emphasis>Period.</emphasis>
Elizabeth D. Zwicky torture tested all the backup programs discussed
here. The clear choice for preserving all your data and all the
peculiarities of Unix filesystems is &man.dump.8;. Elizabeth created
filesystems containing a large variety of unusual conditions (and some
not so unusual ones) and tested each program by do a backup and
restore of that filesystems. The peculiarities included: files with
holes, files with holes and a block of nulls, files with funny
characters in their names, unreadable and unwritable files, devices,
files that change size during the backup, files that are
created/deleted during the backup and more. She presented the results
at LISA V in Oct. 1991. See <ulink
url="http://reality.sgi.com/zwicky_neu/testdump.doc.html">torture-testing Backup and Archive Programs</ulink>.</para>
<para>&man.dump.8; <emphasis>Period.</emphasis> Elizabeth D. Zwicky
torture tested all the backup programs discussed here. The clear
choice for preserving all your data and all the peculiarities of Unix
filesystems is &man.dump.8;. Elizabeth created filesystems containing
a large variety of unusual conditions (and some not so unusual ones)
and tested each program by do a backup and restore of that
filesystems. The peculiarities included: files with holes, files with
holes and a block of nulls, files with funny characters in their
names, unreadable and unwritable files, devices, files that change
size during the backup, files that are created/deleted during the
backup and more. She presented the results at LISA V in Oct. 1991.
See <ulink
url="http://reality.sgi.com/zwicky_neu/testdump.doc.html">torture-testing
Backup and Archive Programs</ulink>.</para>
</sect2>
<sect2>
@ -370,12 +365,12 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
messages. If all your devices are listed and functional, skip on to
step three.</para>
<para>Otherwise, you have to create two custom bootable floppies
which has a kernel that can mount your all of your disks and
access your tape drive. These floppies must contain:
&man.fdisk.8;, &man.disklabel.8;, &man.newfs.8;, &man.mount.8;, and whichever backup
program you use. These programs must be statically linked. If you
use &man.dump.8;, the floppy must contain
<para>Otherwise, you have to create two custom bootable floppies which
has a kernel that can mount your all of your disks and access your
tape drive. These floppies must contain:
&man.fdisk.8;, &man.disklabel.8;, &man.newfs.8;, &man.mount.8;, and
whichever backup program you use. These programs must be statically
linked. If you use &man.dump.8;, the floppy must contain
&man.restore.8;.</para>
<para>Third, create backup tapes regularly. Any changes that you make
@ -385,19 +380,19 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
<para>Fourth, test the floppies (either <filename>boot.flp</filename>
and <filename>fixit.flp</filename> or the two custom bootable
floppies you made in step two.) and backup tapes. Make notes of the
procedure. Store these notes with the bootable floppy, the printouts
and the backup tapes. You will be so distraught when restoring that
the notes may prevent you from destroying your backup tapes (How?
In place of <command>tar xvf /dev/rst0</command>, you might
accidently type <command>tar cvf /dev/rst0</command> and over-write
your backup tape).</para>
procedure. Store these notes with the bootable floppy, the
printouts and the backup tapes. You will be so distraught when
restoring that the notes may prevent you from destroying your backup
tapes (How? In place of <command>tar xvf /dev/rst0</command>, you
might accidently type <command>tar cvf /dev/rst0</command> and
over-write your backup tape).</para>
<para>For an added measure of security, make bootable floppies and two
backup tapes each time. Store one of each at a remote location. A
remote location is NOT the basement of the same office building. A
number of firms in the World Trade Center learned this lesson the
hard way. A remote location should be physically separated from your
computers and disk drives by a significant distance.</para>
hard way. A remote location should be physically separated from
your computers and disk drives by a significant distance.</para>
<para>An example script for creating a bootable floppy:</para>
@ -586,13 +581,13 @@ chmod 644 /mnt/etc/passwd
/mnt</command>) the root partition of your first disk. If the
disklabel was damaged, use &man.disklabel.8; to re-partition and
label the disk to match the label that your printed and saved. Use
&man.newfs.8; to re-create the
filesystems. Re-mount the root partition of the floppy read-write
(<command>mount -u -o rw /mnt</command>). Use your backup program
and backup tapes to recover the data for this filesystem (e.g.
<command>restore vrf /dev/st0</command>). Unmount the filesystem
(e.g. <command>umount /mnt</command>) Repeat for each filesystem
that was damaged.</para>
&man.newfs.8; to re-create the filesystems. Re-mount the root
partition of the floppy read-write (<command>mount -u -o rw
/mnt</command>). Use your backup program and backup tapes to
recover the data for this filesystem (e.g. <command>restore vrf
/dev/st0</command>). Unmount the filesystem (e.g. <command>umount
/mnt</command>) Repeat for each filesystem that was
damaged.</para>
<para>Once your system is running, backup your data onto new tapes.
Whatever caused the crash or data loss may strike again. An another

89
en/handbook/basics/chapter.sgml
View file

@ -1,33 +1,27 @@
<chapter id="basics">
<chapter id="basics">
<title>Unix Basics</title>
<sect1 id="basics-man">
<title>The Online Manual</title>
<para>The most comprehensive documentation on FreeBSD is in the form
of <emphasis>man pages</emphasis>. Nearly every program on the
system comes with a short reference manual explaining the basic
operation and various arguments. These manuals can be view with the
<command>man</command>
command. Use of the <command>man</command> command is simple:</para>
<para>The most comprehensive documentation on FreeBSD is in the form of
<emphasis>man pages</emphasis>. Nearly every program on the system
comes with a short reference manual explaining the basic operation and
various arguments. These manuals can be view with the
<command>man</command> command. Use of the <command>man</command>
command is simple:</para>
<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>
<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput>
</screen>
<para><replaceable>command</replaceable> is
the name of the command you wish to learn about. For example, to
learn more about <command>ls</command> command type:</para>
<para><replaceable>command</replaceable> is the name of the command you
wish to learn about. For example, to learn more about
<command>ls</command> command type:</para>
<screen>&prompt.user; <userinput>man ls</userinput></screen>
<para>The online manual is divided up into numbered sections:</para>
<orderedlist>
<listitem>
<para>User commands</para>
</listitem>
@ -59,57 +53,47 @@
<listitem>
<para>System maintenance and operation commands</para>
</listitem>
</orderedlist>
<para>In some cases, the same topic may appear in more than
one section of the on-line manual. For example, there is a
<command>chmod</command>
user command and a <function>chmod()</function> system call. In
this case, you can tell the <command>man</command> command which one you want by
specifying the section:</para>
<para>In some cases, the same topic may appear in more than one section of
the on-line manual. For example, there is a <command>chmod</command>
user command and a <function>chmod()</function> system call. In this
case, you can tell the <command>man</command> command which one you want
by specifying the section:</para>
<screen>&prompt.user; <userinput>man 1 chmod</userinput></screen>
<para>This will display the manual page for the user
command <command>chmod</command>. References to a
particular section of the on-line manual are traditionally placed in
parenthesis in written documentation, so &man.chmod.1; refers to the
<command>chmod</command>
user command and &man.chmod.2; refers to the
<para>This will display the manual page for the user command
<command>chmod</command>. References to a particular section of the
on-line manual are traditionally placed in parenthesis in written
documentation, so &man.chmod.1; refers to the
<command>chmod</command> user command and &man.chmod.2; refers to the
system call.</para>
<para>This is fine if you know the name of the command and simply wish
to know how to use it, but what if you cannot recall the command
name? You can use <command>man</command> to search for keywords in the
command <emphasis>descriptions</emphasis> by using the
<option>-k</option> switch:</para>
<para>This is fine if you know the name of the command and simply wish to
know how to use it, but what if you cannot recall the command name? You
can use <command>man</command> to search for keywords in the command
<emphasis>descriptions</emphasis> by using the <option>-k</option>
switch:</para>
<screen>&prompt.user; <userinput>man -k mail</userinput></screen>
<para>With this command you will be presented with a
list of commands that have the keyword &ldquo;mail&rdquo; in their descriptions.
This is actually functionally equivalent to using the <command>apropos</command>
<para>With this command you will be presented with a list of commands that
have the keyword &ldquo;mail&rdquo; in their descriptions. This is
actually functionally equivalent to using the <command>apropos</command>
command.</para>
<para>So, you are looking at all those fancy commands in
<filename>/usr/bin</filename> but do not even have the faintest idea
what most of them actually do? Simply do a
<screen>&prompt.user; <userinput>cd /usr/bin; man -f *</userinput></screen>
or
<screen>&prompt.user; <userinput>cd /usr/bin; whatis *</userinput></screen>
which does the same thing.</para>
which does the same thing.</para>
</sect1>
<sect1 id="basics-info">
@ -120,20 +104,17 @@
programs come with more extensive hypertext documents called
&ldquo;info&rdquo; files which can be viewed with the
<command>info</command> command or, if you installed
<command>emacs</command>, the info mode of <command>emacs</command>.</para>
<command>emacs</command>, the info mode of
<command>emacs</command>.</para>
<para>To use the &man.info.1; command, simply type:</para>
<screen>&prompt.user; <userinput>info</userinput></screen>
<para>For a brief introduction, type <userinput>h</userinput>. For a quick
command reference, type <userinput>?</userinput>.</para>
<para>For a brief introduction, type <userinput>h</userinput>. For a
quick command reference, type <userinput>?</userinput>.</para>
</sect1>
</chapter>
</chapter>
<!--
Local Variables:

357
en/handbook/bibliography/chapter.sgml
View file

@ -1,13 +1,11 @@
<chapter id="bibliography">
<chapter id="bibliography">
<title>Bibliography</title>
<para>While the manual pages provide the definitive reference for
individual pieces of the FreeBSD operating system, they are notorious
for not illustrating how to put the pieces together to make the whole
operating system run smoothly. For this, there is no substitute for a
good book on UNIX system administration and a good users'
manual.</para>
<para>While the manual pages provide the definitive reference for individual
pieces of the FreeBSD operating system, they are notorious for not
illustrating how to put the pieces together to make the whole operating
system run smoothly. For this, there is no substitute for a good book on
UNIX system administration and a good users' manual.</para>
<sect1>
<title>Books &amp; Magazines Specific to FreeBSD</title>
@ -15,9 +13,7 @@
<para><emphasis>International books &amp;
Magazines:</emphasis></para>
<itemizedlist>
<listitem>
<para><ulink
URL="http://freebsd.csie.nctu.edu.tw/~jdli/book.html">Using
@ -25,13 +21,13 @@
</listitem>
<listitem>
<para>FreeBSD for PC 98'ers (in Japanese), published by SHUWA
System Co, LTD. ISBN 4-87966-468-5 C3055 P2900E.</para>
<para>FreeBSD for PC 98'ers (in Japanese), published by SHUWA System
Co, LTD. ISBN 4-87966-468-5 C3055 P2900E.</para>
</listitem>
<listitem>
<para>FreeBSD (in Japanese), published by CUTT. ISBN
4-906391-22-2 C3055 P2400E.</para>
<para>FreeBSD (in Japanese), published by CUTT. ISBN 4-906391-22-2
C3055 P2400E.</para>
</listitem>
<listitem>
@ -45,9 +41,9 @@
</listitem>
<listitem>
<para>FreeBSD Handbook (Japanese translation), published by
<ulink URL="http://www.ascii.co.jp/">ASCII</ulink>. ISBN
4-7561-1580-2 P3800E.</para>
<para>FreeBSD Handbook (Japanese translation), published by <ulink
URL="http://www.ascii.co.jp/">ASCII</ulink>. ISBN 4-7561-1580-2
P3800E.</para>
</listitem>
<listitem>
@ -56,179 +52,157 @@
</listitem>
<listitem>
<para><ulink url="http://www.pc.mycom.co.uk/FreeBSD/install-manual.html">FreeBSD
Install and Utilization Manual</ulink> (in Japanese),
published by <ulink url="http://www.pc.mycom.co.jp/">Mainichi
Communications Inc.</ulink>.</para>
<para><ulink
url="http://www.pc.mycom.co.uk/FreeBSD/install-manual.html">FreeBSD Install and Utilization Manual</ulink> (in Japanese), published by <ulink url="http://www.pc.mycom.co.jp/">Mainichi Communications Inc.</ulink>.</para>
</listitem>
</itemizedlist>
<para><emphasis>English language books &amp;
Magazines:</emphasis></para>
<para><emphasis>English language books &amp; Magazines:</emphasis></para>
<itemizedlist>
<listitem>
<para><ulink
URL="http://www.cdrom.com/titles/freebsd/bsdbook2.htm">The
Complete FreeBSD</ulink>, published by <ulink
URL="http://www.cdrom.com">Walnut Creek
CDROM</ulink>.</para>
URL="http://www.cdrom.com">Walnut Creek CDROM</ulink>.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>Users' Guides</title>
<itemizedlist>
<listitem>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD User's Reference Manual</emphasis>. O'Reilly
&amp; Associates, Inc., 1994.<!-- <br> --> ISBN
1-56592-075-9</para>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD
User's Reference Manual</emphasis>. O'Reilly &amp; Associates,
Inc., 1994.<!-- <br> --> ISBN 1-56592-075-9</para>
</listitem>
<listitem>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD User's Supplementary Documents</emphasis>.
O'Reilly &amp; Associates, Inc., 1994.<!-- <br> --> ISBN
1-56592-076-7</para>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD
User's Supplementary Documents</emphasis>. O'Reilly &amp;
Associates, Inc., 1994.<!-- <br> --> ISBN 1-56592-076-7</para>
</listitem>
<listitem>
<para><emphasis>UNIX in a Nutshell</emphasis>. O'Reilly
&amp; Associates, Inc., 1990.<!-- <br> --> ISBN
093717520X</para>
<para><emphasis>UNIX in a Nutshell</emphasis>. O'Reilly &amp;
Associates, Inc., 1990.<!-- <br> --> ISBN 093717520X</para>
</listitem>
<listitem>
<para>Mui, Linda. <emphasis>What You Need To Know When You Can't
Find Your UNIX System Administrator</emphasis>. O'Reilly
&amp; Associates, Inc., 1995. <!-- <br> --> ISBN 1-56592-104-6</para>
<para>Mui, Linda. <emphasis>What You Need To Know When You Can't Find
Your UNIX System Administrator</emphasis>. O'Reilly &amp;
Associates, Inc., 1995. <!-- <br> --> ISBN 1-56592-104-6</para>
</listitem>
<listitem>
<para><ulink URL="http://www-wks.acs.ohio-state.edu/">Ohio State
University</ulink> has written a <ulink
URL="http://www-wks.acs.ohio-state.edu/unix_course/unix.html">UNIX Introductory Course</ulink> which is available online in HTML and postscript format.</para>
URL="http://www-wks.acs.ohio-state.edu/unix_course/unix.html">UNIX
Introductory Course</ulink> which is available online in HTML and
postscript format.</para>
</listitem>
<listitem>
<para><ulink url="http://www.jp.FreeBSD.ORG/">Jpman Project,
Japan FreeBSD Users Group</ulink>. <ulink
url="http://www.pc.mycom.co.jp/FreeBSD/urm.html">FreeBSD
User's Reference Manual</ulink> (Japanese translation).
<ulink url="http://www.pc.mycom.co.jp/">Mainichi
Communications Inc.</ulink>, 1998. ISBN4-8399-0088-4
P3800E.</para>
<para><ulink url="http://www.jp.FreeBSD.ORG/">Jpman Project, Japan
FreeBSD Users Group</ulink>. <ulink
url="http://www.pc.mycom.co.jp/FreeBSD/urm.html">FreeBSD User's
Reference Manual</ulink> (Japanese translation). <ulink
url="http://www.pc.mycom.co.jp/">Mainichi Communications
Inc.</ulink>, 1998. ISBN4-8399-0088-4 P3800E.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>Administrators' Guides</title>
<itemizedlist>
<listitem>
<para>Albitz, Paul and Liu, Cricket. <emphasis>DNS and
BIND</emphasis>, 2nd Ed. O'Reilly &amp; Associates, Inc.,
1997. <!-- <br> --> ISBN 1-56592-236-0</para>
BIND</emphasis>, 2nd Ed. O'Reilly &amp; Associates, Inc., 1997.
<!-- <br> --> ISBN 1-56592-236-0</para>
</listitem>
<listitem>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD System Manager's Manual</emphasis>. O'Reilly
&amp; Associates, Inc., 1994. <!-- <br> --> ISBN
1-56592-080-5</para>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD
System Manager's Manual</emphasis>. O'Reilly &amp; Associates,
Inc., 1994. <!-- <br> --> ISBN 1-56592-080-5</para>
</listitem>
<listitem>
<para>Costales, Brian, et al. <emphasis>Sendmail</emphasis>, 2nd
Ed. O'Reilly &amp; Associates, Inc., 1997.<!-- <br> --> ISBN
<para>Costales, Brian, et al. <emphasis>Sendmail</emphasis>, 2nd Ed.
O'Reilly &amp; Associates, Inc., 1997.<!-- <br> --> ISBN
1-56592-222-0</para>
</listitem>
<listitem>
<para>Frisch, &AElig;leen. <emphasis>Essential System
Administration</emphasis>, 2nd Ed. O'Reilly &amp;
Associates, Inc., 1995. <!-- <br> -->ISBN 1-56592-127-5</para>
Administration</emphasis>, 2nd Ed. O'Reilly &amp; Associates,
Inc., 1995. <!-- <br> -->ISBN 1-56592-127-5</para>
</listitem>
<listitem>
<para>Hunt, Craig. <emphasis>TCP/IP Network
Administration</emphasis>. O'Reilly &amp; Associates, Inc.,
1992. <!-- <br> --> ISBN 0-937175-82-X</para>
Administration</emphasis>. O'Reilly &amp; Associates, Inc., 1992.
<!-- <br> --> ISBN 0-937175-82-X</para>
</listitem>
<listitem>
<para>Nemeth, Evi. <emphasis>UNIX System Administration
Handbook</emphasis>. 2nd Ed. Prentice Hall, 1995. <!-- <br>
--> ISBN 0131510517</para>
Handbook</emphasis>. 2nd Ed. Prentice Hall, 1995. <!-- <br> -->
ISBN 0131510517</para>
</listitem>
<listitem>
<para>Stern, Hal <emphasis>Managing NFS and NIS</emphasis>
O'Reilly &amp; Associates, Inc., 1991. <!-- <br> --> ISBN
<para>Stern, Hal <emphasis>Managing NFS and NIS</emphasis> O'Reilly
&amp; Associates, Inc., 1991. <!-- <br> --> ISBN
0-937175-75-7</para>
</listitem>
<listitem>
<para><ulink url="http://www.jp.FreeBSD.ORG/">Jpman Project,
Japan FreeBSD Users Group</ulink>. <ulink
url="http://www.pc.mycom.co.jp/FreeBSD/sam.html">FreeBSD
System Administrator's Manual</ulink> (Japanese translation).
<ulink url="http://www.pc.mycom.co.jp/">Mainichi
Communications Inc.</ulink>, 1998. ISBN4-8399-0109-0
P3300E.</para>
<para><ulink url="http://www.jp.FreeBSD.ORG/">Jpman Project, Japan
FreeBSD Users Group</ulink>. <ulink
url="http://www.pc.mycom.co.jp/FreeBSD/sam.html">FreeBSD System
Administrator's Manual</ulink> (Japanese translation). <ulink
url="http://www.pc.mycom.co.jp/">Mainichi Communications
Inc.</ulink>, 1998. ISBN4-8399-0109-0 P3300E.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>Programmers' Guides</title>
<itemizedlist>
<listitem>
<para>Asente, Paul. <emphasis>X Window System
Toolkit</emphasis>. Digital Press. <!-- <br> --> ISBN
1-55558-051-3</para>
<para>Asente, Paul. <emphasis>X Window System Toolkit</emphasis>.
Digital Press. <!-- <br> --> ISBN 1-55558-051-3</para>
</listitem>
<listitem>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD Programmer's Reference Manual</emphasis>.
O'Reilly &amp; Associates, Inc., 1994. <!-- <br> --> ISBN
1-56592-078-3</para>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD
Programmer's Reference Manual</emphasis>. O'Reilly &amp;
Associates, Inc., 1994. <!-- <br> --> ISBN 1-56592-078-3</para>
</listitem>
<listitem>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD Programmer's Supplementary
Documents</emphasis>. O'Reilly &amp; Associates, Inc., 1994.
<!-- <br> --> ISBN 1-56592-079-1</para>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD
Programmer's Supplementary Documents</emphasis>. O'Reilly &amp;
Associates, Inc., 1994. <!-- <br> --> ISBN 1-56592-079-1</para>
</listitem>
<listitem>
<para>Harbison, Samuel P. and Steele, Guy L. Jr. <emphasis>C: A
Reference Manual</emphasis>. 4rd ed. Prentice Hall, 1995.
<!-- <br> -->ISBN 0-13-326224-3</para>
Reference Manual</emphasis>. 4rd ed. Prentice Hall, 1995. <!--
<br> -->ISBN 0-13-326224-3</para>
</listitem>
<listitem>
<para>Kernighan, Brian and Dennis M. Ritchie. <emphasis>The C
Programming Language.</emphasis>. PTR Prentice Hall, 1988.
<!-- <br> --> ISBN 0-13-110362-9</para>
Programming Language.</emphasis>. PTR Prentice Hall, 1988. <!--
<br> --> ISBN 0-13-110362-9</para>
</listitem>
<listitem>
@ -238,15 +212,14 @@
</listitem>
<listitem>
<para>Plauger, P. J. <emphasis>The Standard C
Library</emphasis>. Prentice Hall, 1992. <!-- <br> --> ISBN
0-13-131509-9</para>
<para>Plauger, P. J. <emphasis>The Standard C Library</emphasis>.
Prentice Hall, 1992. <!-- <br> --> ISBN 0-13-131509-9</para>
</listitem>
<listitem>
<para>Stevens, W. Richard. <emphasis>Advanced Programming in the
UNIX Environment</emphasis>. Reading, Mass. :
Addison-Wesley, 1992<!-- <br> --> ISBN 0-201-56317-7</para>
<para>Stevens, W. Richard. <emphasis>Advanced Programming in the UNIX
Environment</emphasis>. Reading, Mass. : Addison-Wesley, 1992<!--
<br> --> ISBN 0-201-56317-7</para>
</listitem>
<listitem>
@ -257,72 +230,66 @@
<listitem>
<para>Wells, Bill. &ldquo;Writing Serial Drivers for UNIX&rdquo;.
<emphasis>Dr. Dobb's Journal</emphasis>. 19(15), December
1994. pp68-71, 97-99.</para>
<emphasis>Dr. Dobb's Journal</emphasis>. 19(15), December 1994.
pp68-71, 97-99.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>Operating System Internals</title>
<itemizedlist>
<listitem>
<para>Andleigh, Prabhat K. <emphasis>UNIX System
Architecture</emphasis>. Prentice-Hall, Inc., 1990.<!-- <br>
--> ISBN 0-13-949843-5</para>
Architecture</emphasis>. Prentice-Hall, Inc., 1990.<!-- <br> -->
ISBN 0-13-949843-5</para>
</listitem>
<listitem>
<para>Jolitz, William. &ldquo;Porting UNIX to the
386&rdquo;. <emphasis>Dr.
Dobb's Journal</emphasis>. January 1991-July 1992.</para>
<para>Jolitz, William. &ldquo;Porting UNIX to the 386&rdquo;.
<emphasis>Dr. Dobb's Journal</emphasis>. January 1991-July
1992.</para>
</listitem>
<listitem>
<para>Leffler, Samuel J., Marshall Kirk McKusick, Michael J
Karels and John Quarterman <emphasis>The Design and
Implementation of the 4.3BSD UNIX Operating
System</emphasis>. Reading, Mass. : Addison-Wesley,
1989.<!-- <br> --> ISBN 0-201-06196-1</para>
<para>Leffler, Samuel J., Marshall Kirk McKusick, Michael J Karels and
John Quarterman <emphasis>The Design and Implementation of the
4.3BSD UNIX Operating System</emphasis>. Reading, Mass. :
Addison-Wesley, 1989.<!-- <br> --> ISBN 0-201-06196-1</para>
</listitem>
<listitem>
<para>Leffler, Samuel J., Marshall Kirk McKusick, <emphasis>The
Design and Implementation of the 4.3BSD UNIX Operating
System: Answer Book</emphasis>. Reading, Mass. :
Addison-Wesley, 1991.<!-- <br> --> ISBN 0-201-54629-9</para>
<para>Leffler, Samuel J., Marshall Kirk McKusick, <emphasis>The Design
and Implementation of the 4.3BSD UNIX Operating System: Answer
Book</emphasis>. Reading, Mass. : Addison-Wesley, 1991.<!-- <br>
--> ISBN 0-201-54629-9</para>
</listitem>
<listitem>
<para>McKusick, Marshall Kirk, Keith Bostic, Michael J Karels,
and John Quarterman. <emphasis>The Design and Implementation
of the 4.4BSD Operating System</emphasis>. Reading, Mass. :
<para>McKusick, Marshall Kirk, Keith Bostic, Michael J Karels, and
John Quarterman. <emphasis>The Design and Implementation of the
4.4BSD Operating System</emphasis>. Reading, Mass. :
Addison-Wesley, 1996.<!-- <br> --> ISBN 0-201-54979-4</para>
</listitem>
<listitem>
<para>Stevens, W. Richard. <emphasis>TCP/IP Illustrated, Volume
1: The Protocols</emphasis>. Reading, Mass. :
Addison-Wesley, 1996.<!-- <br> --> ISBN 0-201-63346-9</para>
<para>Stevens, W. Richard. <emphasis>TCP/IP Illustrated, Volume 1:
The Protocols</emphasis>. Reading, Mass. : Addison-Wesley,
1996.<!-- <br> --> ISBN 0-201-63346-9</para>
</listitem>
<listitem>
<para>Schimmel, Curt. <emphasis>Unix Systems for Modern
Architectures</emphasis>. Reading, Mass. : Addison-Wesley,
1994. ISBN 0-201-63338-8</para>
Architectures</emphasis>. Reading, Mass. : Addison-Wesley, 1994.
ISBN 0-201-63338-8</para>
</listitem>
<listitem>
<para>Stevens, W. Richard. <emphasis>TCP/IP Illustrated, Volume
3: TCP for Transactions, HTTP, NNTP and the UNIX Domain
Protocols</emphasis>. Reading, Mass. : Addison-Wesley,
1996.<!-- <br> --> ISBN 0-201-63495-3</para>
<para>Stevens, W. Richard. <emphasis>TCP/IP Illustrated, Volume 3:
TCP for Transactions, HTTP, NNTP and the UNIX Domain
Protocols</emphasis>. Reading, Mass. : Addison-Wesley, 1996.<!--
<br> --> ISBN 0-201-63495-3</para>
</listitem>
<listitem>
@ -333,52 +300,41 @@
<listitem>
<para>Wright, Gary R. and W. Richard Stevens. <emphasis>TCP/IP
Illustrated, Volume 2: The Implementation</emphasis>.
Reading, Mass. : Addison-Wesley, 1995.<!-- <br> --> ISBN
0-201-63354-X</para>
Illustrated, Volume 2: The Implementation</emphasis>. Reading,
Mass. : Addison-Wesley, 1995.<!-- <br> --> ISBN 0-201-63354-X</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>Security Reference</title>
<itemizedlist>
<listitem>
<para>Cheswick, William R. and Steven M. Bellovin.
<emphasis>Firewalls and Internet Security: Repelling the Wily
Hacker</emphasis>. Reading, Mass. : Addison-Wesley,
1995.<!-- <br> --> ISBN 0-201-63357-4</para>
<para>Cheswick, William R. and Steven M. Bellovin. <emphasis>Firewalls
and Internet Security: Repelling the Wily Hacker</emphasis>.
Reading, Mass. : Addison-Wesley, 1995.<!-- <br> --> ISBN
0-201-63357-4</para>
</listitem>
<listitem>
<para>Garfinkel, Simson and Gene Spafford. <emphasis>Practical
UNIX Security</emphasis>. 2nd Ed. O'Reilly &amp; Associates,
Inc., 1996. <!-- <br> --> ISBN 1-56592-148-8</para>
<para>Garfinkel, Simson and Gene Spafford. <emphasis>Practical UNIX
Security</emphasis>. 2nd Ed. O'Reilly &amp; Associates, Inc.,
1996. <!-- <br> --> ISBN 1-56592-148-8</para>
</listitem>
<listitem>
<para>Garfinkel, Simson. <emphasis>PGP Pretty Good
Privacy</emphasis> O'Reilly &amp; Associates, Inc., 1995.
<!-- <br> --> ISBN 1-56592-098-8</para>
Privacy</emphasis> O'Reilly &amp; Associates, Inc., 1995. <!--
<br> --> ISBN 1-56592-098-8</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>Hardware Reference</title>
<itemizedlist>
<listitem>
<para>Anderson, Don and Tom Shanley. <emphasis>Pentium Processor
System Architecture</emphasis>. 2nd Ed. Reading, Mass. :
@ -386,10 +342,9 @@
</listitem>
<listitem>
<para>Ferraro, Richard F. <emphasis>Programmer's Guide to the
EGA, VGA, and Super VGA Cards</emphasis>. 3rd ed. Reading,
Mass. : Addison-Wesley, 1995.<!-- <br> --> ISBN
0-201-62490-7</para>
<para>Ferraro, Richard F. <emphasis>Programmer's Guide to the EGA,
VGA, and Super VGA Cards</emphasis>. 3rd ed. Reading, Mass. :
Addison-Wesley, 1995.<!-- <br> --> ISBN 0-201-62490-7</para>
</listitem>
<listitem>
@ -400,48 +355,43 @@
</listitem>
<listitem>
<para>Shanley, Tom. <emphasis>80486 System
Architecture</emphasis>. 3rd ed. Reading, Mass. :
Addison-Wesley, 1995. <!-- <br> -->ISBN 0-201-40994-1</para>
<para>Shanley, Tom. <emphasis>80486 System Architecture</emphasis>.
3rd ed. Reading, Mass. : Addison-Wesley, 1995. <!-- <br> -->ISBN
0-201-40994-1</para>
</listitem>
<listitem>
<para>Shanley, Tom. <emphasis>ISA System
Architecture</emphasis>. 3rd ed. Reading, Mass. :
Addison-Wesley, 1995.<!-- <br> --> ISBN 0-201-40996-8</para>
<para>Shanley, Tom. <emphasis>ISA System Architecture</emphasis>.
3rd ed. Reading, Mass. : Addison-Wesley, 1995.<!-- <br> --> ISBN
0-201-40996-8</para>
</listitem>
<listitem>
<para>Shanley, Tom. <emphasis>PCI System
Architecture</emphasis>. 3rd ed. Reading, Mass. :
Addison-Wesley, 1995. <!-- <br> -->ISBN 0-201-40993-3</para>
<para>Shanley, Tom. <emphasis>PCI System Architecture</emphasis>.
3rd ed. Reading, Mass. : Addison-Wesley, 1995. <!-- <br> -->ISBN
0-201-40993-3</para>
</listitem>
<listitem>
<para>Van Gilluwe, Frank. <emphasis>The Undocumented
PC</emphasis>. Reading, Mass: Addison-Wesley Pub. Co.,
1994.<!-- <br> --> ISBN 0-201-62277-7</para>
<para>Van Gilluwe, Frank. <emphasis>The Undocumented PC</emphasis>.
Reading, Mass: Addison-Wesley Pub. Co., 1994.<!-- <br> --> ISBN
0-201-62277-7</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>UNIX History</title>
<itemizedlist>
<listitem>
<para>Lion, John <emphasis>Lion's Commentary on UNIX, 6th Ed.
With Source Code</emphasis>. ITP Media Group, 1996.<!-- <br>
--> ISBN 1573980137</para>
<para>Lion, John <emphasis>Lion's Commentary on UNIX, 6th Ed. With
Source Code</emphasis>. ITP Media Group, 1996.<!-- <br> --> ISBN
1573980137</para>
</listitem>
<listitem>
<para>Raymond, Eric s. <emphasis>The New Hacker's Dictonary, 3rd
<para>Raymond, Eric S. <emphasis>The New Hacker's Dictonary, 3rd
edition</emphasis>. MIT Press, 1996.<!-- <br> --> ISBN
0-262-68092-0<!-- <br> --> Also known as the <ulink
URL="http://www.ccil.org/jargon/jargon.html">Jargon
@ -449,32 +399,32 @@
</listitem>
<listitem>
<para>Salus, Peter H. <emphasis>A quarter century of
UNIX</emphasis>. Addison-Wesley Publishing Company, Inc.,
1994.<!-- <br> --> ISBN 0-201-54777-5</para>
<para>Salus, Peter H. <emphasis>A quarter century of UNIX</emphasis>.
Addison-Wesley Publishing Company, Inc., 1994.<!-- <br> --> ISBN
0-201-54777-5</para>
</listitem>
<listitem>
<para>Simon Garfinkel, Daniel Weise, Steven Strassmann.
<emphasis>The UNIX-HATERS Handbook</emphasis>. IDG Books
Worldwide, Inc., 1994.<!-- <br> --> ISBN 1-56884-203-1</para>
<para>Simon Garfinkel, Daniel Weise, Steven Strassmann. <emphasis>The
UNIX-HATERS Handbook</emphasis>. IDG Books Worldwide, Inc.,
1994.<!-- <br> --> ISBN 1-56884-203-1</para>
</listitem>
<listitem>
<para>Don Libes, Sandy Ressler <emphasis>Life with
UNIX</emphasis> &mdash; special edition. Prentice-Hall, Inc.,
1989.<!-- <br> --> ISBN 0-13-536657-7</para>
<para>Don Libes, Sandy Ressler <emphasis>Life with UNIX</emphasis>
&mdash; special edition. Prentice-Hall, Inc., 1989.<!-- <br> -->
ISBN 0-13-536657-7</para>
</listitem>
<listitem>
<para><emphasis>The BSD family tree</emphasis>. 1997.<!-- <br>
--> <ulink
url="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/misc/bsd-family-tree">ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/misc/bsd-family-tree</ulink> or <ulink URL="file:/usr/share/misc/bsd-family-tree">local</ulink> on a FreeBSD-current machine.</para>
<para><emphasis>The BSD family tree</emphasis>. 1997.<!-- <br> -->
<ulink
url="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/misc/bsd-family-tree">ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/misc/bsd-family-tree</ulink> or <ulink URL="file:/usr/share/misc/bsd-family-tree">local</ulink> on a FreeBSD-current machine.</para>
</listitem>
<listitem>
<para><emphasis>The BSD Release Announcements
collection</emphasis>. 1997.<!-- <br> --> <ulink
<para><emphasis>The BSD Release Announcements collection</emphasis>.
1997.<!-- <br> --> <ulink
URL="http://www.de.FreeBSD.ORG/de/ftp/releases/">http://www.de.FreeBSD.ORG/de/ftp/releases/</ulink></para>
</listitem>
@ -487,19 +437,18 @@ url="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/misc/bsd-family
<listitem>
<para><emphasis>Old BSD releases from the Computer Systems Research
group (CSRG)</emphasis>. <ulink
url="http://www.mckusick.com/csrg/">http://www.mckusick.com/csrg/</ulink>: The 4CD set covers all BSD versions from 1BSD to 4.4BSD and 4.4BSD-Lite2 (but not 2.11BSD, unfortunately). As well, the last disk holds the final sources plus the SCCS files.</para>
url="http://www.mckusick.com/csrg/">http://www.mckusick.com/csrg/</ulink>:
The 4CD set covers all BSD versions from 1BSD to 4.4BSD and
4.4BSD-Lite2 (but not 2.11BSD, unfortunately). As well, the last
disk holds the final sources plus the SCCS files.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>Magazines and Journals</title>
<itemizedlist>
<listitem>
<para><emphasis>The C/C++ Users Journal</emphasis>. R&amp;D
Publications Inc. ISSN 1075-2838</para>
@ -510,13 +459,9 @@ url="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/misc/bsd-family
Administrators</emphasis> Miller Freeman, Inc., ISSN
1061-2688</para>
</listitem>
</itemizedlist>
</sect1>
</chapter>
</chapter>
<!--
Local Variables:

6188
en/handbook/contrib/chapter.sgml
View file

File diff suppressed because it is too large Load diff

1916
en/handbook/cutting-edge/chapter.sgml
View file

File diff suppressed because it is too large Load diff

27
en/handbook/disks/chapter.sgml
View file

@ -11,8 +11,8 @@
<para>Login as user <username>root</username>. After you've installed the
drive, inspect <filename>/var/run/dmesg.boot</filename> to ensure the new
disk was found. Continuing with our example, the newly added drive will be
<filename>sd1</filename> and we want to mount it on
disk was found. Continuing with our example, the newly added drive will
be <filename>sd1</filename> and we want to mount it on
<filename>/1</filename>. (if you are adding an IDE drive substitute
<filename>wd</filename> for <filename>sd</filename>)</para>
@ -37,7 +37,7 @@
<sect1>
<title>Using sysinstall</title>
<para> You may use <command>/stand/sysinstall</command> to partition and
<para>You may use <command>/stand/sysinstall</command> to partition and
label a new disk using its easy to use menus. Either login as user
<username>root</username> or use the <command>su</command> command. Run
<command>/stand/sysinstall</command> and enter the
@ -56,19 +56,20 @@
<literal>YES</literal>. Write the changes to the disk using
<command>W</command>. Now exit the FDISK editor using
<command>q</command>. Next you will be asked about the Master Boot
Record. Since you are adding a disk to an already running system, choose
<literal>None</literal>.</para>
Record. Since you are adding a disk to an already running system,
choose <literal>None</literal>.</para>
<para>Next enter the <literal>Disk Label Editor</literal>. This is where
you will create the traditional BSD partitions. A disk can have up to
eight partitions, labeled a-h. A few of the partition labels have
special uses. The <literal>a</literal> partition is used for the root
partition (<filename>/</filename>). Thus only your system disk (e.g, the
disk you boot from) should have an <literal>a</literal> partition. The
<literal>b</literal> partition is used for swap partitions, and you may
have many disks with swap partitions. The <literal>c</literal> partition
addresses the entire disk in dedicated mode, or the entire FreeBSD slice
in slice mode. The other partitions are for general use.</para>
partition (<filename>/</filename>). Thus only your system disk (e.g,
the disk you boot from) should have an <literal>a</literal> partition.
The <literal>b</literal> partition is used for swap partitions, and you
may have many disks with swap partitions. The <literal>c</literal>
partition addresses the entire disk in dedicated mode, or the entire
FreeBSD slice in slice mode. The other partitions are for general
use.</para>
<para>Sysinstall's Label editor favors the <literal>e</literal> partition
for non-root, non-swap partitions. With in the Label editor, create a
@ -107,7 +108,6 @@
&ldquo;appropriate&rdquo; any partition it finds which it doesn't
understand.</para>
<screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/rsd1 bs=1k count=1</userinput>
&prompt.root; <userinput>disklabel -Brw sd1 auto</userinput>
&prompt.root; <userinput>disklabel -e sd</userinput>1 # create the `e' partition
@ -116,17 +116,14 @@
&prompt.root; <userinput>vi /etc/fstab</userinput> # add an entry for /dev/sd1e
&prompt.root; <userinput>mount /1</userinput></screen>
<para>An alternate method is:</para>
<screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/rsd1 count=2</userinput>
&prompt.root; <userinput>disklabel /dev/rsd1 | disklabel -BrR sd1 /dev/stdin</userinput>
&prompt.root; <userinput>newfs /dev/rsd1e</userinput>
&prompt.root; <userinput>mkdir -p /1</userinput>
&prompt.root; <userinput>vi /etc/fstab</userinput> # add an entry for /dev/sd1e
&prompt.root; <userinput>mount /1</userinput></screen>
</sect2>
</sect1>

672
en/handbook/eresources/chapter.sgml
View file

File diff suppressed because it is too large Load diff

16
en/handbook/handbook.sgml
View file

@ -36,19 +36,21 @@
<abstract>
<para>Welcome to FreeBSD! This handbook covers the installation and day
to day use of <emphasis>FreeBSD Release &rel.current;</emphasis>. This
manual is a <emphasis>work in progress</emphasis> and is the work of
many individuals. Many sections do not yet exist and some of those
to day use of <emphasis>FreeBSD Release &rel.current;</emphasis>.
This manual is a <emphasis>work in progress</emphasis> and is the work
of many individuals. Many sections do not yet exist and some of those
that do exist need to be updated. If you are interested in helping
with this project, send email to the &a.doc;. The latest version of
this document is always available from the <ulink
URL="http://www.FreeBSD.ORG/">FreeBSD World Wide Web server</ulink>.
It may also be downloaded in <ulink url="handbook.latin1">plain
text</ulink>, <ulink url="handbook.ps">postscript</ulink> or <ulink
url="handbook-html.tar.gz">HTML</ulink> with HTTP or gzip'd from the <ulink
url="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/doc/">FreeBSD FTP server</ulink> or one of the numerous <link
text</ulink>, <ulink url="handbook.ps">postscript</ulink> or <ulink
url="handbook-html.tar.gz">HTML</ulink> with HTTP or gzip'd from the
<ulink url="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/doc/">FreeBSD FTP
server</ulink> or one of the numerous <link
linkend="mirrors-ftp">mirror sites</link>. You may also want to
<ulink URL="http://www.FreeBSD.ORG/search.html">Search the Handbook</ulink>.</para>
<ulink URL="http://www.FreeBSD.ORG/search.html">Search the
Handbook</ulink>.</para>
</abstract>
</bookinfo>

4585
en/handbook/hw/chapter.sgml
View file

File diff suppressed because it is too large Load diff

886
en/handbook/install/chapter.sgml
View file

File diff suppressed because it is too large Load diff

1108
en/handbook/internals/chapter.sgml
View file

File diff suppressed because it is too large Load diff

760
en/handbook/introduction/chapter.sgml
View file

@ -1,170 +1,156 @@
<chapter id="introduction">
<chapter id="introduction">
<title>Introduction</title>
<para>FreeBSD is a 4.4BSD-Lite based operating system for Intel
architecture (x86) based PCs. For an overview of FreeBSD, see
<link linkend="nutshell">FreeBSD in a nutshell</link>. For a
history of the project, read <link linkend="history">a brief
history of FreeBSD</link>. To see a description of the latest release,
read <link linkend="relnotes">about the current
release</link>. If you're interested in contributing something to the
FreeBSD project (code, equipment, sacks of unmarked bills), please see
about <link linkend="contrib">contributing to FreeBSD</link>.</para>
<para>FreeBSD is a 4.4BSD-Lite based operating system for Intel architecture
(x86) based PCs. For an overview of FreeBSD, see <link
linkend="nutshell">FreeBSD in a nutshell</link>. For a history of the
project, read <link linkend="history">a brief history of FreeBSD</link>.
To see a description of the latest release, read <link
linkend="relnotes">about the current release</link>. If you're
interested in contributing something to the FreeBSD project (code,
equipment, sacks of unmarked bills), please see about <link
linkend="contrib">contributing to FreeBSD</link>.</para>
<sect1 id="nutshell">
<title>FreeBSD in a Nutshell</title>
<para>FreeBSD is a state of the art operating system for personal
computers based on the Intel CPU architecture, which includes the
386, 486 and Pentium processors (both SX and DX versions). Intel
compatible CPUs from AMD and Cyrix are supported as well. FreeBSD
provides you with many advanced features previously available only
on much more expensive computers. These features include:</para>
computers based on the Intel CPU architecture, which includes the 386,
486 and Pentium processors (both SX and DX versions). Intel compatible
CPUs from AMD and Cyrix are supported as well. FreeBSD provides you
with many advanced features previously available only on much more
expensive computers. These features include:</para>
<itemizedlist>
<listitem>
<para><emphasis>Preemptive multitasking</emphasis> with
dynamic priority adjustment to ensure smooth and fair sharing
of the computer between applications and users.</para>
<para><emphasis>Preemptive multitasking</emphasis> with dynamic
priority adjustment to ensure smooth and fair sharing of the
computer between applications and users.</para>
</listitem>
<listitem>
<para><emphasis>Multiuser</emphasis> access means that
many people can use a FreeBSD system simultaneously for a
variety of things. System peripherals such as printers and
tape drives are also properly SHARED BETWEEN ALL users on the
system.</para>
<para><emphasis>Multiuser</emphasis> access means that many people can
use a FreeBSD system simultaneously for a variety of things. System
peripherals such as printers and tape drives are also properly
SHARED BETWEEN ALL users on the system.</para>
</listitem>
<listitem>
<para>Complete <emphasis>TCP/IP networking</emphasis>
including SLIP, PPP, NFS and NIS support. This means that
your FreeBSD machine can inter-operate easily with other
systems as well act as an enterprise server, providing vital
functions such as NFS (remote file access) and e-mail services
or putting your organization on the Internet with WWW, ftp,
routing and firewall (security) services.</para>
<para>Complete <emphasis>TCP/IP networking</emphasis> including SLIP,
PPP, NFS and NIS support. This means that your FreeBSD machine can
inter-operate easily with other systems as well act as an enterprise
server, providing vital functions such as NFS (remote file access)
and e-mail services or putting your organization on the Internet
with WWW, ftp, routing and firewall (security) services.</para>
</listitem>
<listitem>
<para><emphasis>Memory protection</emphasis> ensures
that applications (or users) cannot interfere with each other.
One application crashing will not affect others in any
way.</para>
<para><emphasis>Memory protection</emphasis> ensures that applications
(or users) cannot interfere with each other. One application
crashing will not affect others in any way.</para>
</listitem>
<listitem>
<para>FreeBSD is a <emphasis>32-bit</emphasis>
operating system and was designed as such from the ground
up.</para>
<para>FreeBSD is a <emphasis>32-bit</emphasis> operating system and
was designed as such from the ground up.</para>
</listitem>
<listitem>
<para>The industry standard <emphasis>X Window
System</emphasis> (X11R6) provides a graphical user
interface (GUI) for the cost of a common VGA card and monitor
and comes with full sources.</para>
<para>The industry standard <emphasis>X Window System</emphasis>
(X11R6) provides a graphical user interface (GUI) for the cost of a
common VGA card and monitor and comes with full sources.</para>
</listitem>
<listitem>
<para><emphasis>Binary compatibility</emphasis> with
many programs built for SCO, BSDI, NetBSD, Linux and
386BSD.</para>
<para><emphasis>Binary compatibility</emphasis> with many programs
built for SCO, BSDI, NetBSD, Linux and 386BSD.</para>
</listitem>
<listitem>
<para>Hundreds of <emphasis>ready-to-run</emphasis>
applications are available from the FreeBSD <emphasis>ports</emphasis> and <emphasis>packages</emphasis> collection. Why search the net
when you can find it all right here?</para>
<para>Hundreds of <emphasis>ready-to-run</emphasis> applications are
available from the FreeBSD <emphasis>ports</emphasis> and
<emphasis>packages</emphasis> collection. Why search the net when
you can find it all right here?</para>
</listitem>
<listitem>
<para>Thousands of additional and <emphasis>easy-to-port</emphasis> applications available on
the Internet. FreeBSD is source code compatible with most
popular commercial Unix systems and thus most applications
require few, if any, changes to compile.</para>
<para>Thousands of additional and <emphasis>easy-to-port</emphasis>
applications available on the Internet. FreeBSD is source code
compatible with most popular commercial Unix systems and thus most
applications require few, if any, changes to compile.</para>
</listitem>
<listitem>
<para>Demand paged <emphasis>virtual memory</emphasis>
and &ldquo;merged VM/buffer cache&rdquo; design efficiently satisfies
applications with large appetites for memory while still
maintaining interactive response to other users.</para>
<para>Demand paged <emphasis>virtual memory</emphasis> and
&ldquo;merged VM/buffer cache&rdquo; design efficiently satisfies
applications with large appetites for memory while still maintaining
interactive response to other users.</para>
</listitem>
<listitem>
<para><emphasis>Shared libraries</emphasis> (the Unix
equivalent of MS-Windows DLLs) provide for efficient use of
disk space and memory.</para>
<para><emphasis>Shared libraries</emphasis> (the Unix equivalent of
MS-Windows DLLs) provide for efficient use of disk space and
memory.</para>
</listitem>
<listitem>
<para>A full complement of <emphasis>C</emphasis>,
<emphasis>C++</emphasis> and <emphasis>Fortran</emphasis> development tools. Many
additional languages for advanced research and development are
also available in the ports and packages collection.</para>
<emphasis>C++</emphasis> and <emphasis>Fortran</emphasis>
development tools. Many additional languages for advanced research
and development are also available in the ports and packages
collection.</para>
</listitem>
<listitem>
<para><emphasis>Source code</emphasis> for the entire
system means you have the greatest degree of control over your
environment. Why be locked into a proprietary solution and at
the mercy of your vendor when you can have a truly Open
System?</para>
<para><emphasis>Source code</emphasis> for the entire system means you
have the greatest degree of control over your environment. Why be
locked into a proprietary solution and at the mercy of your vendor
when you can have a truly Open System?</para>
</listitem>
<listitem>
<para>Extensive <emphasis>on-line
documentation</emphasis>.</para>
<para>Extensive <emphasis>on-line documentation</emphasis>.</para>
</listitem>
<listitem>
<para><emphasis>And many more!</emphasis></para>
</listitem>
</itemizedlist>
<para>FreeBSD is based on the 4.4BSD-Lite release from Computer Systems
Research Group (CSRG) at the University of California at Berkeley, and
carries on the distinguished tradition of BSD systems development. In
addition to the fine work provided by CSRG, the FreeBSD Project has put
in many thousands of hours in fine tuning the system for maximum
performance and reliability in real-life load situations. As many of
the commercial giants struggle to field PC operating systems with such
features, performance and reliability, FreeBSD can offer them
<emphasis>now</emphasis>!</para>
<para>FreeBSD is based on the 4.4BSD-Lite release from Computer
Systems Research Group (CSRG) at the University of California at
Berkeley, and carries on the distinguished tradition of BSD systems
development. In addition to the fine work provided by CSRG, the
FreeBSD Project has put in many thousands of hours in fine tuning
the system for maximum performance and reliability in real-life load
situations. As many of the commercial giants struggle to field PC
operating systems with such features, performance and reliability,
FreeBSD can offer them <emphasis>now</emphasis>!</para>
<para>The applications to which FreeBSD can be put are truly limited
only by your own imagination. From software development to factory
automation, inventory control to azimuth correction of remote
satellite antennae; if it can be done with a commercial UNIX product
then it is more than likely that you can do it with FreeBSD, too!
FreeBSD also benefits significantly from the literally thousands of
high quality applications developed by research centers and
universities around the world, often available at little to no cost.
Commercial applications are also available and appearing in greater
numbers every day.</para>
<para>Because the source code for FreeBSD itself is generally
available, the system can also be customized to an almost unheard of
degree for special applications or projects, and in ways not
generally possible with operating systems from most major commercial
vendors. Here is just a sampling of some of the applications in
which people are currently using FreeBSD:</para>
<para>The applications to which FreeBSD can be put are truly limited only
by your own imagination. From software development to factory
automation, inventory control to azimuth correction of remote satellite
antennae; if it can be done with a commercial UNIX product then it is
more than likely that you can do it with FreeBSD, too! FreeBSD also
benefits significantly from the literally thousands of high quality
applications developed by research centers and universities around the
world, often available at little to no cost. Commercial applications are
also available and appearing in greater numbers every day.</para>
<para>Because the source code for FreeBSD itself is generally available,
the system can also be customized to an almost unheard of degree for
special applications or projects, and in ways not generally possible
with operating systems from most major commercial vendors. Here is just
a sampling of some of the applications in which people are currently
using FreeBSD:</para>
<itemizedlist>
<listitem>
<para><emphasis>Internet Services:</emphasis> The
robust TCP/IP networking built into FreeBSD makes it an ideal
platform for a variety of Internet services such as:</para>
<itemizedlist>
<para><emphasis>Internet Services:</emphasis> The robust TCP/IP
networking built into FreeBSD makes it an ideal platform for a
variety of Internet services such as:</para>
<itemizedlist>
<listitem>
<para>FTP servers</para>
</listitem>
@ -192,71 +178,62 @@
<listitem>
<para>And more...</para>
</listitem>
</itemizedlist>
<para>You can easily start out small with an
inexpensive 386 class PC and upgrade as your enterprise
grows.</para>
<para>You can easily start out small with an inexpensive 386 class PC
and upgrade as your enterprise grows.</para>
</listitem>
<listitem>
<para><emphasis>Education:</emphasis> Are you a student
of computer science or a related engineering field? There is
no better way of learning about operating systems, computer
architecture and networking than the hands on, under the hood
experience that FreeBSD can provide. A number of freely
available CAD, mathematical and graphic design packages also
make it highly useful to those whose primary interest in a
computer is to get <emphasis>other</emphasis> work
done!</para>
<para><emphasis>Education:</emphasis> Are you a student of computer
science or a related engineering field? There is no better way of
learning about operating systems, computer architecture and
networking than the hands on, under the hood experience that FreeBSD
can provide. A number of freely available CAD, mathematical and
graphic design packages also make it highly useful to those whose
primary interest in a computer is to get <emphasis>other</emphasis>
work done!</para>
</listitem>
<listitem>
<para><emphasis>Research:</emphasis> With source code
for the entire system available, FreeBSD is an excellent
platform for research in operating systems as well as other
branches of computer science. FreeBSD's freely available
nature also makes it possible for remote groups to collaborate
on ideas or shared development without having to worry about
special licensing agreements or limitations on what may be
discussed in open forums.</para>
<para><emphasis>Research:</emphasis> With source code for the entire
system available, FreeBSD is an excellent platform for research in
operating systems as well as other branches of computer science.
FreeBSD's freely available nature also makes it possible for remote
groups to collaborate on ideas or shared development without having
to worry about special licensing agreements or limitations on what
may be discussed in open forums.</para>
</listitem>
<listitem>
<para><emphasis>Networking:</emphasis> Need a new
router? A name server (DNS)? A firewall to keep people out
of your internal network? FreeBSD can easily turn that unused
386 or 486 PC sitting in the corner into an advanced router
with sophisticated packet filtering capabilities.</para>
<para><emphasis>Networking:</emphasis> Need a new router? A name
server (DNS)? A firewall to keep people out of your internal
network? FreeBSD can easily turn that unused 386 or 486 PC sitting
in the corner into an advanced router with sophisticated packet
filtering capabilities.</para>
</listitem>
<listitem>
<para><emphasis>X Window workstation:</emphasis>
FreeBSD is a fine choice for an inexpensive X terminal
solution, either using the freely available XFree86 server or
one of the excellent commercial servers provided by X Inside.
Unlike an X terminal, FreeBSD allows many applications to be
run locally, if desired, thus relieving the burden on a
central server. FreeBSD can even boot &ldquo;diskless&rdquo;, making
individual workstations even cheaper and easier to
administer.</para>
<para><emphasis>X Window workstation:</emphasis> FreeBSD is a fine
choice for an inexpensive X terminal solution, either using the
freely available XFree86 server or one of the excellent commercial
servers provided by X Inside. Unlike an X terminal, FreeBSD allows
many applications to be run locally, if desired, thus relieving the
burden on a central server. FreeBSD can even boot
&ldquo;diskless&rdquo;, making individual workstations even cheaper
and easier to administer.</para>
</listitem>
<listitem>
<para><emphasis>Software Development:</emphasis> The
basic FreeBSD system comes with a full complement of
development tools including the renowned GNU C/C++ compiler
and debugger.</para>
<para><emphasis>Software Development:</emphasis> The basic FreeBSD
system comes with a full complement of development tools including
the renowned GNU C/C++ compiler and debugger.</para>
</listitem>
</itemizedlist>
<para>FreeBSD is available in both source and binary form on CDROM and
via anonymous ftp. See <link linkend="mirrors">Obtaining
FreeBSD</link> for more details.</para>
<para>FreeBSD is available in both source and binary form on CDROM and via
anonymous ftp. See <link linkend="mirrors">Obtaining FreeBSD</link>
for more details.</para>
</sect1>
<sect1 id="history">
@ -265,101 +242,96 @@
<para><emphasis>Contributed by &a.jkh;</emphasis>.</para>
<para>The FreeBSD project had its genesis in the early part of 1993,
partially as an outgrowth of the &ldquo;Unofficial 386BSD Patchkit&rdquo; by the
patchkit's last 3 coordinators: Nate Williams, Rod Grimes and
myself.</para>
partially as an outgrowth of the &ldquo;Unofficial 386BSD
Patchkit&rdquo; by the patchkit's last 3 coordinators: Nate Williams,
Rod Grimes and myself.</para>
<para>Our original goal was to produce an intermediate snapshot of
386BSD in order to fix a number of problems with it that the
patchkit mechanism just was not capable of solving. Some of you may
remember the early working title for the project being &ldquo;386BSD 0.5&rdquo;
or &ldquo;386BSD Interim&rdquo; in reference to that fact.</para>
<para>Our original goal was to produce an intermediate snapshot of 386BSD
in order to fix a number of problems with it that the patchkit mechanism
just was not capable of solving. Some of you may remember the early
working title for the project being &ldquo;386BSD 0.5&rdquo; or
&ldquo;386BSD Interim&rdquo; in reference to that fact.</para>
<para>386BSD was Bill Jolitz's operating system, which had been up to
that point suffering rather severely from almost a year's worth of
neglect. As the patchkit swelled ever more uncomfortably with each
passing day, we were in unanimous agreement that something had to be
done and decided to try and assist Bill by providing this interim
&ldquo;cleanup&rdquo; snapshot. Those plans came to a rude halt when Bill
Jolitz suddenly decided to withdraw his sanction from the project
and without any clear indication of what would be done
instead.</para>
<para>386BSD was Bill Jolitz's operating system, which had been up to that
point suffering rather severely from almost a year's worth of neglect.
As the patchkit swelled ever more uncomfortably with each passing day,
we were in unanimous agreement that something had to be done and decided
to try and assist Bill by providing this interim &ldquo;cleanup&rdquo;
snapshot. Those plans came to a rude halt when Bill Jolitz suddenly
decided to withdraw his sanction from the project and without any clear
indication of what would be done instead.</para>
<para>It did not take us long to decide that the goal remained
worthwhile, even without Bill's support, and so we adopted the name
&ldquo;FreeBSD&rdquo;, coined by David Greenman. Our initial objectives were
set after consulting with the system's current users and, once it
became clear that the project was on the road to perhaps even
becoming a reality, I contacted Walnut Creek CDROM with an eye
towards improving FreeBSD's distribution channels for those many
unfortunates without easy access to the Internet. Walnut Creek
CDROM not only supported the idea of distributing FreeBSD on CD but
went so far as to provide the project with a machine to work on and
a fast Internet connection. Without Walnut Creek CDROM's almost
unprecedented degree of faith in what was, at the time, a completely
unknown project, it is quite unlikely that FreeBSD would have gotten
as far, as fast, as it has today.</para>
<para>It did not take us long to decide that the goal remained worthwhile,
even without Bill's support, and so we adopted the name
&ldquo;FreeBSD&rdquo;, coined by David Greenman. Our initial objectives
were set after consulting with the system's current users and, once it
became clear that the project was on the road to perhaps even becoming a
reality, I contacted Walnut Creek CDROM with an eye towards improving
FreeBSD's distribution channels for those many unfortunates without easy
access to the Internet. Walnut Creek CDROM not only supported the idea
of distributing FreeBSD on CD but went so far as to provide the project
with a machine to work on and a fast Internet connection. Without
Walnut Creek CDROM's almost unprecedented degree of faith in what was,
at the time, a completely unknown project, it is quite unlikely that
FreeBSD would have gotten as far, as fast, as it has today.</para>
<para>The first CDROM (and general net-wide) distribution was FreeBSD
1.0, released in December of 1993. This was based on the
4.3BSD-Lite (&ldquo;Net/2&rdquo;) tape from U.C. Berkeley, with many components
also provided by 386BSD and the Free Software Foundation. It was a
fairly reasonable success for a first offering, and we followed it
with the highly successful FreeBSD 1.1 release in May of
1994.</para>
<para>The first CDROM (and general net-wide) distribution was FreeBSD 1.0,
released in December of 1993. This was based on the 4.3BSD-Lite
(&ldquo;Net/2&rdquo;) tape from U.C. Berkeley, with many components also
provided by 386BSD and the Free Software Foundation. It was a fairly
reasonable success for a first offering, and we followed it with the
highly successful FreeBSD 1.1 release in May of 1994.</para>
<para>Around this time, some rather unexpected storm clouds formed on
the horizon as Novell and U.C. Berkeley settled their long-running
lawsuit over the legal status of the Berkeley Net/2 tape. A
condition of that settlement was U.C. Berkeley's concession that
large parts of Net/2 were &ldquo;encumbered&rdquo; code and the property of
Novell, who had in turn acquired it from AT&amp;T some time
previously. What Berkeley got in return was Novell's &ldquo;blessing&rdquo;
that the 4.4BSD-Lite release, when it was finally released, would be
declared unencumbered and all existing Net/2 users would be strongly
encouraged to switch. This included FreeBSD, and the project was
given until the end of July 1994 to stop shipping its own Net/2
based product. Under the terms of that agreement, the project was
allowed one last release before the deadline, that release being
FreeBSD 1.1.5.1.</para>
<para>Around this time, some rather unexpected storm clouds formed on the
horizon as Novell and U.C. Berkeley settled their long-running lawsuit
over the legal status of the Berkeley Net/2 tape. A condition of that
settlement was U.C. Berkeley's concession that large parts of Net/2 were
&ldquo;encumbered&rdquo; code and the property of Novell, who had in
turn acquired it from AT&amp;T some time previously. What Berkeley got
in return was Novell's &ldquo;blessing&rdquo; that the 4.4BSD-Lite
release, when it was finally released, would be declared unencumbered
and all existing Net/2 users would be strongly encouraged to switch.
This included FreeBSD, and the project was given until the end of July
1994 to stop shipping its own Net/2 based product. Under the terms of
that agreement, the project was allowed one last release before the
deadline, that release being FreeBSD 1.1.5.1.</para>
<para>FreeBSD then set about the arduous task of literally
re-inventing itself from a completely new and rather incomplete set
of 4.4BSD-Lite bits. The &ldquo;Lite&rdquo; releases were light in part because
Berkeley's CSRG had removed large chunks of code required for
actually constructing a bootable running system (due to various
legal requirements) and the fact that the Intel port of 4.4 was
highly incomplete. It took the project until December of 1994 to
make this transition, and in January of 1995 it released FreeBSD 2.0
to the net and on CDROM. Despite being still more than a little
rough around the edges, the release was a significant success and
was followed by the more robust and easier to install FreeBSD 2.0.5
release in June of 1995.</para>
<para>FreeBSD then set about the arduous task of literally re-inventing
itself from a completely new and rather incomplete set of 4.4BSD-Lite
bits. The &ldquo;Lite&rdquo; releases were light in part because
Berkeley's CSRG had removed large chunks of code required for actually
constructing a bootable running system (due to various legal
requirements) and the fact that the Intel port of 4.4 was highly
incomplete. It took the project until December of 1994 to make this
transition, and in January of 1995 it released FreeBSD 2.0 to the net
and on CDROM. Despite being still more than a little rough around the
edges, the release was a significant success and was followed by the
more robust and easier to install FreeBSD 2.0.5 release in June of
1995.</para>
<para>We released FreeBSD 2.1.5 in August of 1996, and it appeared to
be popular enough among the ISP and commercial communities that
another release along the 2.1-stable branch was merited. This was
FreeBSD 2.1.7.1, released in February 1997 and capping the end of
mainstream development on 2.1-stable. Now in maintenance mode, only
security enhancements and other critical bug fixes will be done on
this branch (RELENG_2_1_0).</para>
<para>We released FreeBSD 2.1.5 in August of 1996, and it appeared to be
popular enough among the ISP and commercial communities that another
release along the 2.1-stable branch was merited. This was FreeBSD
2.1.7.1, released in February 1997 and capping the end of mainstream
development on 2.1-stable. Now in maintenance mode, only security
enhancements and other critical bug fixes will be done on this branch
(RELENG_2_1_0).</para>
<para>FreeBSD 2.2 was branched from the development mainline
(&ldquo;-current&rdquo;) in November 1996 as the RELENG_2_2 branch, and the
first full release (2.2.1) was released in April, 1997. Further
releases along the 2.2 branch were done in the Summer and Fall of
'97, the latest being 2.2.7 which appeared in late July of '98.
The first official 3.0 release appeared in October, 1998 and the
last release on the 2.2 branch, 2.2.8, appeared in November,
1998.</para>
(&ldquo;-current&rdquo;) in November 1996 as the RELENG_2_2 branch, and
the first full release (2.2.1) was released in April, 1997. Further
releases along the 2.2 branch were done in the Summer and Fall of '97,
the latest being 2.2.7 which appeared in late July of '98. The first
official 3.0 release appeared in October, 1998 and the last release on
the 2.2 branch, 2.2.8, appeared in November, 1998.</para>
<para>The tree branched again on Jan 20, 1999. This led to
4.0-current and a 3.x-stable branch, from which 3.1 will be
released on February 15th, 1999.</para>
<para>The tree branched again on Jan 20, 1999. This led to 4.0-current
and a 3.x-stable branch, from which 3.1 will be released on February
15th, 1999.</para>
<para>Long term development projects will continue to take place in
the 4.0-current branch and SNAPshot releases of 4.0 on CDROM (and,
of course, on the net).</para>
<para>Long term development projects will continue to take place in the
4.0-current branch and SNAPshot releases of 4.0 on CDROM (and, of
course, on the net).</para>
</sect1>
<sect1 id="goals">
@ -367,25 +339,24 @@
<para><emphasis>Contributed by &a.jkh;</emphasis>.</para>
<para>The goals of the FreeBSD Project are to provide software that
may be used for any purpose and without strings attached. Many of
us have a significant investment in the code (and project) and would
certainly not mind a little financial compensation now and then, but
we're definitely not prepared to insist on it. We believe that our
first and foremost &ldquo;mission&rdquo; is to provide code to any and all
comers, and for whatever purpose, so that the code gets the widest
possible use and provides the widest possible benefit. This is, I
believe, one of the most fundamental goals of Free Software and one
that we enthusiastically support.</para>
<para>The goals of the FreeBSD Project are to provide software that may be
used for any purpose and without strings attached. Many of us have a
significant investment in the code (and project) and would certainly not
mind a little financial compensation now and then, but we're definitely
not prepared to insist on it. We believe that our first and foremost
&ldquo;mission&rdquo; is to provide code to any and all comers, and for
whatever purpose, so that the code gets the widest possible use and
provides the widest possible benefit. This is, I believe, one of the
most fundamental goals of Free Software and one that we enthusiastically
support.</para>
<para>That code in our source tree which falls under the GNU Public
License (GPL) or GNU Library Public License (GLPL) comes with
slightly more strings attached, though at least on the side of
enforced access rather than the usual opposite. Due to the
additional complexities that can evolve in the commercial use of GPL
software, we do, however, endeavor to replace such software with
submissions under the more relaxed BSD copyright whenever possible.</para>
License (GPL) or GNU Library Public License (GLPL) comes with slightly
more strings attached, though at least on the side of enforced access
rather than the usual opposite. Due to the additional complexities that
can evolve in the commercial use of GPL software, we do, however,
endeavor to replace such software with submissions under the more
relaxed BSD copyright whenever possible.</para>
</sect1>
<sect1 id="development">
@ -396,222 +367,225 @@
<para>The development of FreeBSD is a very open and flexible process,
FreeBSD being literally built from the contributions of hundreds of
people around the world, as can be seen from our <link
linkend="staff">list of contributors</link>. We are constantly
on the lookout for new developers and ideas, and those interested in
becoming more closely involved with the project need simply contact
us at the &a.hackers;. Those who prefer to work more independently
are also accommodated, and they are free to use our FTP facilities
at <ulink
URL="ftp://ftp.freebsd.org/pub/FreeBSD/incoming">ftp.freebsd.org</ulink> to distribute their own patches or work-in-progress sources. The &a.announce; is also available to those wishing to make other FreeBSD users aware of major areas of work.</para>
<para>Useful things to know about the FreeBSD project and its
development process, whether working independently or in close
cooperation:</para>
linkend="staff">list of contributors</link>. We are constantly on the
lookout for new developers and ideas, and those interested in becoming
more closely involved with the project need simply contact us at the
&a.hackers;. Those who prefer to work more independently are also
accommodated, and they are free to use our FTP facilities at <ulink
URL="ftp://ftp.freebsd.org/pub/FreeBSD/incoming">ftp.freebsd.org</ulink>
to distribute their own patches or work-in-progress sources. The
&a.announce; is also available to those wishing to make other FreeBSD
users aware of major areas of work.</para>
<para>Useful things to know about the FreeBSD project and its development
process, whether working independently or in close cooperation:</para>
<variablelist>
<varlistentry><term>The CVS
repository<anchor id="development-cvs-repository"></term>
<varlistentry>
<term>The CVS repository<anchor
id="development-cvs-repository"></term>
<listitem>
<para>The central source tree for FreeBSD is maintained by
<ulink
URL="http://www.cyclic.com/cyclic-pages/CVS-sheet.html">CVS</ulink> (Concurrent Version System), a freely available source code control tool which comes bundled with FreeBSD. The primary <ulink URL="http://www.freebsd.org/cgi/cvsweb.cgi">CVS repository</ulink> resides on a machine in Concord CA, USA from where it is replicated to numerous mirror machines throughout the world. The CVS tree, as well as the <link linkend="current">-current</link> and <link
linkend="stable">-stable</link> trees which are checked
out of it, can be easily replicated to your own machine as
well. Please refer to the
<link linkend="synching">Synchronizing your source
<para>The central source tree for FreeBSD is maintained by <ulink
URL="http://www.cyclic.com/cyclic-pages/CVS-sheet.html">CVS</ulink>
(Concurrent Version System), a freely available source code
control tool which comes bundled with FreeBSD. The primary <ulink
URL="http://www.freebsd.org/cgi/cvsweb.cgi">CVS
repository</ulink> resides on a machine in Concord CA, USA from
where it is replicated to numerous mirror machines throughout the
world. The CVS tree, as well as the <link
linkend="current">-current</link> and <link
linkend="stable">-stable</link> trees which are checked out of
it, can be easily replicated to your own machine as well. Please
refer to the <link linkend="synching">Synchronizing your source
tree</link> section for more information on doing this.</para>
</listitem>
</varlistentry>
<varlistentry><term>The committers
list<anchor id="development-committers"></term>
<varlistentry>
<term>The committers list<anchor id="development-committers"></term>
<listitem>
<para>The <link linkend="staff-committers">committers</link>
are the people who have <emphasis>write</emphasis> access to
the CVS tree, and are thus authorized to make modifications
to the FreeBSD source (the term &ldquo;committer&rdquo; comes from the
&man.cvs.1; <command>commit</command> command, which is used to
bring new changes into the CVS repository). The best way of
making submissions for review by the committers list is to
use the &man.send-pr.1; command, though if something appears to be jammed in the system then you may also reach them by sending mail to <email>committers@freebsd.org</email>.</para>
<para>The <link linkend="staff-committers">committers</link> are the
people who have <emphasis>write</emphasis> access to the CVS tree,
and are thus authorized to make modifications to the FreeBSD
source (the term &ldquo;committer&rdquo; comes from the
&man.cvs.1; <command>commit</command> command, which is used
to bring new changes into the CVS repository). The best way of
making submissions for review by the committers list is to use the
&man.send-pr.1; command, though if something appears to be
jammed in the system then you may also reach them by sending mail
to <email>committers@freebsd.org</email>.</para>
</listitem>
</varlistentry>
<varlistentry><term>The FreeBSD core
team<anchor id="development-core"></term>
<varlistentry>
<term>The FreeBSD core team<anchor id="development-core"></term>
<listitem>
<para>The <link linkend="staff-core">FreeBSD core
team</link> would be equivalent to the board of directors if
the FreeBSD Project were a company. The primary task of the
core team is to make sure the project, as a whole, is in
good shape and is heading in the right directions. Inviting
dedicated and responsible developers to join our group of
committers is one of the functions of the core team, as is
the recruitment of new core team members as others move on.
Most current members of the core team started as committers
who's addiction to the project got the better of
<para>The <link linkend="staff-core">FreeBSD core team</link> would
be equivalent to the board of directors if the FreeBSD Project
were a company. The primary task of the core team is to make sure
the project, as a whole, is in good shape and is heading in the
right directions. Inviting dedicated and responsible developers
to join our group of committers is one of the functions of the
core team, as is the recruitment of new core team members as
others move on. Most current members of the core team started as
committers who's addiction to the project got the better of
them.</para>
<para>Some core team members also have specific <link
linkend="staff-who">areas of responsibility</link>,
meaning that they are committed to ensuring that some large
portion of the system works as advertised.</para>
linkend="staff-who">areas of responsibility</link>, meaning that
they are committed to ensuring that some large portion of the
system works as advertised.</para>
<note>
<para>Most members of the core team are volunteers when it
comes to FreeBSD development and do not benefit from the
project financially, so &ldquo;commitment&rdquo; should also not be
<para>Most members of the core team are volunteers when it comes
to FreeBSD development and do not benefit from the project
financially, so &ldquo;commitment&rdquo; should also not be
misconstrued as meaning &ldquo;guaranteed support.&rdquo; The
&ldquo;board of directors&rdquo; analogy above is not
actually very accurate, and it may be more suitable to say
that these are the people who gave up their lives in favor
of FreeBSD against their better judgement! <!-- smiley --><emphasis>;)</emphasis></para>
&ldquo;board of directors&rdquo; analogy above is not actually
very accurate, and it may be more suitable to say that these are
the people who gave up their lives in favor of FreeBSD against
their better judgement! <!-- smiley
--><emphasis>;)</emphasis></para>
</note>
</listitem>
</varlistentry>
<varlistentry><term>Outside
contributors</term>
<varlistentry>
<term>Outside contributors</term>
<listitem>
<para>Last, but definitely not least, the largest group of
developers are the users themselves who provide feedback and
bug-fixes to us on an almost constant basis. The primary
way of keeping in touch with FreeBSD's more non-centralized
development is to subscribe to the &a.hackers; (see <link
linkend="eresources-mail">mailing list
info</link>) where such things are discussed.</para>
bug-fixes to us on an almost constant basis. The primary way of
keeping in touch with FreeBSD's more non-centralized development
is to subscribe to the &a.hackers; (see <link
linkend="eresources-mail">mailing list info</link>) where such
things are discussed.</para>
<para><link linkend="contrib-additional">The list</link> of
those who have contributed something which made its way into
our source tree is a long and growing one, so why not join
it by contributing something back to FreeBSD today?
<!-- smiley --><emphasis>:-)</emphasis></para>
<para><link linkend="contrib-additional">The list</link> of those
who have contributed something which made its way into our source
tree is a long and growing one, so why not join it by contributing
something back to FreeBSD today? <!-- smiley
--><emphasis>:-)</emphasis></para>
<para>Providing code is not the only way of contributing to
the project; for a more complete list of things that need
doing, please refer to the <link linkend="contrib">how to
<para>Providing code is not the only way of contributing to the
project; for a more complete list of things that need doing,
please refer to the <link linkend="contrib">how to
contribute</link> section in this handbook.</para>
</listitem>
</varlistentry>
</variablelist>
<para>In summary, our development model is organized as a loose set of
concentric circles. The centralized model is designed for the
convenience of the <emphasis>users</emphasis> of FreeBSD, who are
thereby provided with an easy way of tracking one central code base,
not to keep potential contributors out! Our desire is to present a
stable operating system with a large set of coherent <link
linkend="ports">application programs</link> that the users can easily install
and use, and this model works very well in accomplishing
thereby provided with an easy way of tracking one central code base, not
to keep potential contributors out! Our desire is to present a stable
operating system with a large set of coherent <link
linkend="ports">application programs</link> that the users can easily
install and use, and this model works very well in accomplishing
that.</para>
<para>All we ask of those who would join us as FreeBSD developers is
some of the same dedication its current people have to its continued
<para>All we ask of those who would join us as FreeBSD developers is some
of the same dedication its current people have to its continued
success!</para>
</sect1>
<sect1 id="relnotes">
<title>About the Current Release</title>
<para>FreeBSD is a freely available, full source 4.4BSD-Lite based
release for Intel i386/i486/Pentium/PentiumPro/Pentium II (or
compatible) based PC's. It is based primarily on software from U.C.
Berkeley's CSRG group, with some enhancements from NetBSD, OpenBSD,
386BSD, and the Free Software Foundation.</para>
<para>FreeBSD is a freely available, full source 4.4BSD-Lite based release
for Intel i386/i486/Pentium/PentiumPro/Pentium II (or compatible) based
PC's. It is based primarily on software from U.C. Berkeley's CSRG
group, with some enhancements from NetBSD, OpenBSD, 386BSD, and the Free
Software Foundation.</para>
<para>Since our release of FreeBSD 2.0 in January of 95, the
performance, feature set, and stability of FreeBSD has improved
dramatically. The largest change is a revamped virtual memory
system with a merged VM/file buffer cache that not only increases
performance, but reduces FreeBSD's memory footprint, making a 5MB
configuration a more acceptable minimum. Other enhancements include
full NIS client and server support, transaction TCP support,
dial-on-demand PPP, an improved SCSI subsystem, early ISDN support,
support for FDDI and Fast Ethernet (100Mbit) adapters, improved
support for the Adaptec 2940 (WIDE and narrow) and many hundreds of
bug fixes.</para>
<para>Since our release of FreeBSD 2.0 in January of 95, the performance,
feature set, and stability of FreeBSD has improved dramatically. The
largest change is a revamped virtual memory system with a merged VM/file
buffer cache that not only increases performance, but reduces FreeBSD's
memory footprint, making a 5MB configuration a more acceptable minimum.
Other enhancements include full NIS client and server support,
transaction TCP support, dial-on-demand PPP, an improved SCSI subsystem,
early ISDN support, support for FDDI and Fast Ethernet (100Mbit)
adapters, improved support for the Adaptec 2940 (WIDE and narrow) and
many hundreds of bug fixes.</para>
<para>We have also taken the comments and suggestions of many of our
users to heart and have attempted to provide what we hope is a more
sane and easily understood installation process. Your feedback on
this (constantly evolving) process is especially welcome!</para>
<para>We have also taken the comments and suggestions of many of our users
to heart and have attempted to provide what we hope is a more sane and
easily understood installation process. Your feedback on this
(constantly evolving) process is especially welcome!</para>
<para>In addition to the base distributions, FreeBSD offers a new
ported software collection with hundreds of commonly sought-after
programs. At the end of August 1998 there were more than 1700 ports!
The list of ports ranges from http (WWW) servers, to games,
languages, editors and almost everything in between. The entire
ports collection requires approximately 26MB of storage, all ports
being expressed as &ldquo;deltas&rdquo; to their original sources. This
makes it much easier for us to update ports, and greatly reduces
the disk space demands made by the older 1.0 ports collection. To
compile a port, you simply change to the directory of the program
you wish to install, type <command>make all</command> followed by <command>make install</command>
after successful compilation and let the system do the rest. The
full original distribution for each port you build is retrieved
dynamically off the CDROM or a local ftp site, so you need only
enough disk space to build the ports you want. (Almost) every port
is also provided as a pre-compiled &ldquo;package&rdquo; which can be installed
with a simple command (pkg_add) by those who do not wish to compile
their own ports from source.</para>
<para>A number of additional documents which you may find very helpful
in the process of installing and using FreeBSD may now also be found
in the <filename>/usr/share/doc</filename> directory on any machine
running FreeBSD 2.1 or later. You may view the locally installed
manuals with any HTML capable browser using the following
URLs:</para>
<para>In addition to the base distributions, FreeBSD offers a new ported
software collection with hundreds of commonly sought-after programs. At
the end of August 1998 there were more than 1700 ports! The list of
ports ranges from http (WWW) servers, to games, languages, editors and
almost everything in between. The entire ports collection requires
approximately 26MB of storage, all ports being expressed as
&ldquo;deltas&rdquo; to their original sources. This makes it much
easier for us to update ports, and greatly reduces the disk space
demands made by the older 1.0 ports collection. To compile a port, you
simply change to the directory of the program you wish to install, type
<command>make all</command> followed by <command>make install</command>
after successful compilation and let the system do the rest. The full
original distribution for each port you build is retrieved dynamically
off the CDROM or a local ftp site, so you need only enough disk space to
build the ports you want. (Almost) every port is also provided as a
pre-compiled &ldquo;package&rdquo; which can be installed with a simple
command (pkg_add) by those who do not wish to compile their own ports
from source.</para>
<para>A number of additional documents which you may find very helpful in
the process of installing and using FreeBSD may now also be found in the
<filename>/usr/share/doc</filename> directory on any machine running
FreeBSD 2.1 or later. You may view the locally installed manuals with
any HTML capable browser using the following URLs:</para>
<variablelist>
<varlistentry><term>The FreeBSD handbook</term>
<varlistentry>
<term>The FreeBSD handbook</term>
<listitem>
<para><ulink
URL="file:/usr/share/doc/handbook/handbook.html">file:/usr/share/doc/handbook/handbook.html</ulink></para>
</listitem>
</varlistentry>
<varlistentry><term>The FreeBSD FAQ</term>
<varlistentry>
<term>The FreeBSD FAQ</term>
<listitem>
<para><ulink
URL="file:/usr/share/doc/FAQ/FAQ.html">file:/usr/share/doc/FAQ/FAQ.html</ulink></para>
</listitem>
</varlistentry>
</variablelist>
<para>You can also visit the master (and most frequently updated)
copies at <ulink
URL="http://www.freebsd.org">http://www.freebsd.org</ulink>.</para>
<para>The core of FreeBSD does not contain DES code which would
inhibit its being exported outside the United States. There is an
add-on package to the core distribution, for use only in the United
States, that contains the programs that normally use DES. The
auxiliary packages provided separately can be used by anyone. A
freely (from outside the U.S.) exportable European distribution of
DES for our non-U.S. users also exists and is described in the
<ulink URL="../FAQ/FAQ.html">FreeBSD FAQ</ulink>.</para>
<para>If password security for FreeBSD is all you need, and you have
no requirement for copying encrypted passwords from different hosts
(Suns, DEC machines, etc) into FreeBSD password entries, then
FreeBSD's MD5 based security may be all you require! We feel that
our default security model is more than a match for DES, and without
any messy export issues to deal with. If you are outside (or even
inside) the U.S., give it a try!</para>
<para>The core of FreeBSD does not contain DES code which would inhibit
its being exported outside the United States. There is an add-on
package to the core distribution, for use only in the United States,
that contains the programs that normally use DES. The auxiliary
packages provided separately can be used by anyone. A freely (from
outside the U.S.) exportable European distribution of DES for our
non-U.S. users also exists and is described in the <ulink
URL="../FAQ/FAQ.html">FreeBSD FAQ</ulink>.</para>
<para>If password security for FreeBSD is all you need, and you have no
requirement for copying encrypted passwords from different hosts (Suns,
DEC machines, etc) into FreeBSD password entries, then FreeBSD's MD5
based security may be all you require! We feel that our default security
model is more than a match for DES, and without any messy export issues
to deal with. If you are outside (or even inside) the U.S., give it a
try!</para>
</sect1>
</chapter>
</chapter>
<!--
Local Variables:

1684
en/handbook/kernelconfig/chapter.sgml
View file

File diff suppressed because it is too large Load diff

540
en/handbook/kerneldebug/chapter.sgml
View file

@ -1,95 +1,87 @@
<chapter id="kerneldebug">
<chapter id="kerneldebug">
<title>Kernel Debugging</title>
<para><emphasis>Contributed by &a.paul; and &a.joerg;</emphasis></para>
<sect1>
<title>Debugging a Kernel Crash Dump with <command>kgdb</command></title>
<para>Here are some instructions for getting kernel debugging working
on a crash dump. They assume that you have enough swap space for a
crash dump. If you have multiple swap partitions and the first one
is too small to hold the dump, you can configure your kernel to use
an alternate dump device (in the <literal>config
kernel</literal> line), or you can specify an alternate using the
&man.dumpon.8; command. The best way to use &man.dumpon.8; is to set the <literal>dumpdev</literal> variable in
<para>Here are some instructions for getting kernel debugging working on a
crash dump. They assume that you have enough swap space for a crash
dump. If you have multiple swap partitions and the first one is too
small to hold the dump, you can configure your kernel to use an
alternate dump device (in the <literal>config kernel</literal> line), or
you can specify an alternate using the
&man.dumpon.8; command. The best way to use &man.dumpon.8; is to set
the <literal>dumpdev</literal> variable in
<filename>/etc/rc.conf</filename>. Typically you want to specify one of
the swap devices specified in <filename>/etc/fstab</filename>.
Dumps to non-swap devices, tapes for example,
are currently not supported. Config your kernel using
<command>config -g</command>. See <link linkend="kernelconfig">Kernel
Configuration</link> for
details on configuring the FreeBSD kernel.</para>
the swap devices specified in <filename>/etc/fstab</filename>. Dumps to
non-swap devices, tapes for example, are currently not supported. Config
your kernel using <command>config -g</command>. See <link
linkend="kernelconfig">Kernel Configuration</link> for details on
configuring the FreeBSD kernel.</para>
<para>Use the &man.dumpon.8; command to tell the kernel
where to dump to (note that this will have to be done after
configuring the partition in question as swap space via
&man.swapon.8;). This is normally arranged via
<filename>/etc/rc.conf</filename> and <filename>/etc/rc</filename>.
Alternatively, you can hard-code the dump device via the <literal>dump</literal>
clause in the <literal>config</literal> line of your kernel config file. This is
deprecated and should be used only if you want a crash dump from a
kernel that crashes during booting.</para>
<para>Use the &man.dumpon.8; command to tell the kernel where to dump to
(note that this will have to be done after configuring the partition in
question as swap space via &man.swapon.8;). This is normally arranged
via <filename>/etc/rc.conf</filename> and <filename>/etc/rc</filename>.
Alternatively, you can hard-code the dump device via the
<literal>dump</literal> clause in the <literal>config</literal> line of
your kernel config file. This is deprecated and should be used only if
you want a crash dump from a kernel that crashes during booting.</para>
<note>
<para>In the following, the term <command>kgdb</command> refers to
<command>gdb</command> run in &ldquo;kernel debug mode&rdquo;. This can be
accomplished by either starting the <command>gdb</command> with
the option <option>-k</option>, or by linking and starting it
under the name <command>kgdb</command>. This is not being done by
default, however, and the idea is basically deprecated since the
GNU folks do not like their tools to behave differently when
called by another name. This feature may well be discontinued in
further releases.</para>
<command>gdb</command> run in &ldquo;kernel debug mode&rdquo;. This
can be accomplished by either starting the <command>gdb</command> with
the option <option>-k</option>, or by linking and starting it under
the name <command>kgdb</command>. This is not being done by default,
however, and the idea is basically deprecated since the GNU folks do
not like their tools to behave differently when called by another
name. This feature may well be discontinued in further
releases.</para>
</note>
<para>When the kernel has been built make a copy of it, say
<filename>kernel.debug</filename>, and then run <command>strip
-d</command> on the original. Install the original as normal. You
may also install the unstripped kernel, but symbol table lookup time
for some programs will drastically increase, and since the whole
kernel is loaded entirely at boot time and cannot be swapped out
later, several megabytes of physical memory will be wasted.</para>
may also install the unstripped kernel, but symbol table lookup time for
some programs will drastically increase, and since the whole kernel is
loaded entirely at boot time and cannot be swapped out later, several
megabytes of physical memory will be wasted.</para>
<para>If you are testing a new kernel, for example by typing the new
kernel's name at the boot prompt, but need to boot a different one
in order to get your system up and running again, boot it only into
single user state using the <option>-s</option> flag at the boot
prompt, and then perform the following steps:</para>
kernel's name at the boot prompt, but need to boot a different one in
order to get your system up and running again, boot it only into single
user state using the <option>-s</option> flag at the boot prompt, and
then perform the following steps:</para>
<screen>&prompt.root; <userinput>fsck -p</userinput>
&prompt.root; <userinput>mount -a -t ufs</userinput> # so your file system for /var/crash is writable
&prompt.root; <userinput>savecore -N /kernel.panicked /var/crash</userinput>
&prompt.root; <userinput>exit</userinput> # ...to multi-user</screen>
<para>This instructs &man.savecore.8; to
use another kernel for symbol name extraction. It would otherwise
default to the currently running kernel and most likely not do
anything at all since the crash dump and the kernel symbols
differ.</para>
<para>This instructs &man.savecore.8; to use another kernel for symbol
name extraction. It would otherwise default to the currently running
kernel and most likely not do anything at all since the crash dump and
the kernel symbols differ.</para>
<para>Now, after a crash dump, go to
<filename>/sys/compile/WHATEVER</filename> and run <command>kgdb</command>. From <command>kgdb</command>
do:
<filename>/sys/compile/WHATEVER</filename> and run
<command>kgdb</command>. From <command>kgdb</command> do:
<screen><userinput>symbol-file kernel.debug</userinput>
<userinput>exec-file /var/crash/kernel.0</userinput>
<userinput>core-file /var/crash/vmcore.0</userinput></screen>
and voila, you can debug the crash dump using the kernel sources just
like you can for any other program.</para>
and voila, you can debug the crash dump using the
kernel sources just like you can for any other program.</para>
<para>Here is a script log of a <command>kgdb</command>
session illustrating the procedure. Long lines have been folded to
improve readability, and the lines are numbered for reference.
Despite this, it is a real-world error trace taken during the
development of the pcvt console driver.</para>
<para>Here is a script log of a <command>kgdb</command> session
illustrating the procedure. Long lines have been folded to improve
readability, and the lines are numbered for reference. Despite this, it
is a real-world error trace taken during the development of the pcvt
console driver.</para>
<screen> 1:Script started on Fri Dec 30 23:15:22 1994
2:&prompt.root; <userinput>cd /sys/compile/URIAH</userinput>
@ -172,68 +164,65 @@ Dumps to non-swap devices, tapes for example,
79:
80:Script done on Fri Dec 30 23:18:04 1994</screen>
<para>Comments to the above script:</para>
<variablelist>
<varlistentry><term>line 6:</term>
<listitem>
<para>This is a dump taken from within DDB (see below), hence
the panic comment &ldquo;because you said to!&rdquo;, and a rather
long stack trace; the initial reason for going into DDB has
been a page fault trap though.</para>
<varlistentry>
<term>line 6:</term>
<listitem>
<para>This is a dump taken from within DDB (see below), hence the
panic comment &ldquo;because you said to!&rdquo;, and a rather
long stack trace; the initial reason for going into DDB has been a
page fault trap though.</para>
</listitem>
</varlistentry>
<varlistentry><term>line 20:</term>
<varlistentry>
<term>line 20:</term>
<listitem>
<para>This is the location of function
<function>trap()</function> in the stack trace.</para>
<para>This is the location of function <function>trap()</function>
in the stack trace.</para>
</listitem>
</varlistentry>
<varlistentry><term>line 36:</term>
<varlistentry>
<term>line 36:</term>
<listitem>
<para>Force usage of a new stack frame; this is no longer
necessary now. The stack frames are supposed to point to
the right locations now, even in case of a trap. (I do not
have a new core dump handy &lt;g&gt;, my kernel has not
panicked for a rather long time.) From looking at the code
in source line 403, there is a high probability that either
the pointer access for &ldquo;tp&rdquo; was messed up, or the array
access was out of bounds.</para>
<para>Force usage of a new stack frame; this is no longer necessary
now. The stack frames are supposed to point to the right
locations now, even in case of a trap. (I do not have a new core
dump handy &lt;g&gt;, my kernel has not panicked for a rather long
time.) From looking at the code in source line 403, there is a
high probability that either the pointer access for
&ldquo;tp&rdquo; was messed up, or the array access was out of
bounds.</para>
</listitem>
</varlistentry>
<varlistentry><term>line 52:</term>
<varlistentry>
<term>line 52:</term>
<listitem>
<para>The pointer looks suspicious, but happens to be a valid
address.</para>
</listitem>
</varlistentry>
<varlistentry><term>line 56:</term>
<varlistentry>
<term>line 56:</term>
<listitem>
<para>However, it obviously points to garbage, so we have
found our error! (For those unfamiliar with that particular
piece of code: <literal>tp-&gt;t_line</literal>
refers to the line discipline of the console device here,
which must be a rather small integer number.)</para>
<para>However, it obviously points to garbage, so we have found our
error! (For those unfamiliar with that particular piece of code:
<literal>tp-&gt;t_line</literal> refers to the line discipline of
the console device here, which must be a rather small integer
number.)</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1>
@ -244,10 +233,8 @@ Dumps to non-swap devices, tapes for example,
option to the <command>ddd</command> command line you would use
normally. For example;</para>
<screen>&prompt.root; <userinput>ddd -k /var/crash/kernel.0 /var/crash/vmcore.0</userinput></screen>
<para>You should then be able to go about looking at the crash dump using
<command>ddd</command>'d graphical interface.</para>
</sect1>
@ -255,124 +242,115 @@ Dumps to non-swap devices, tapes for example,
<sect1>
<title>Post-mortem Analysis of a Dump</title>
<para>What do you do if a kernel dumped core but you did not expect
it, and it is therefore not compiled using <command>config
-g</command>? Not everything is lost here. Do not panic!</para>
<para>What do you do if a kernel dumped core but you did not expect it,
and it is therefore not compiled using <command>config -g</command>? Not
everything is lost here. Do not panic!</para>
<para>Of course, you still need to enable crash dumps. See above on
the options you have to specify in order to do this.</para>
<para>Of course, you still need to enable crash dumps. See above on the
options you have to specify in order to do this.</para>
<para>Go to your kernel compile directory, and edit the line
containing <literal>COPTFLAGS?=-O</literal>. Add the
<option>-g</option> option there (but <emphasis>do not</emphasis>
change anything on the level of optimization). If you do already
know roughly the probable location of the failing piece of code
(e.g., the <devicename>pcvt</devicename> driver in the example
above), remove all the object files for this code. Rebuild the
kernel. Due to the time stamp change on the Makefile, there will be
some other object files rebuild, for example
<para>Go to your kernel compile directory, and edit the line containing
<literal>COPTFLAGS?=-O</literal>. Add the <option>-g</option> option
there (but <emphasis>do not</emphasis> change anything on the level of
optimization). If you do already know roughly the probable location of
the failing piece of code (e.g., the <devicename>pcvt</devicename>
driver in the example above), remove all the object files for this code.
Rebuild the kernel. Due to the time stamp change on the Makefile, there
will be some other object files rebuild, for example
<filename>trap.o</filename>. With a bit of luck, the added
<option>-g</option> option will not change anything for the
generated code, so you will finally get a new kernel with similar
code to the faulting one but some debugging symbols. You should at
least verify the old and new sizes with the
&man.size.1; command. If there is a mismatch, you
probably need to give up here.</para>
<option>-g</option> option will not change anything for the generated
code, so you will finally get a new kernel with similar code to the
faulting one but some debugging symbols. You should at least verify the
old and new sizes with the
&man.size.1; command. If there is a mismatch, you probably need to
give up here.</para>
<para>Go and examine the dump as described above. The debugging
symbols might be incomplete for some places, as can be seen in the
stack trace in the example above where some functions are displayed
without line numbers and argument lists. If you need more debugging
symbols, remove the appropriate object files and repeat the
<command>kgdb</command> session until you know
enough.</para>
<para>All this is not guaranteed to work, but it will do it fine in
most cases.</para>
<para>Go and examine the dump as described above. The debugging symbols
might be incomplete for some places, as can be seen in the stack trace
in the example above where some functions are displayed without line
numbers and argument lists. If you need more debugging symbols, remove
the appropriate object files and repeat the <command>kgdb</command>
session until you know enough.</para>
<para>All this is not guaranteed to work, but it will do it fine in most
cases.</para>
</sect1>
<sect1>
<title>On-line Kernel Debugging Using DDB</title>
<para>While <command>kgdb</command> as an offline debugger
provides a very high level of user interface, there are some things
it cannot do. The most important ones being breakpointing and
single-stepping kernel code.</para>
<para>While <command>kgdb</command> as an offline debugger provides a very
high level of user interface, there are some things it cannot do. The
most important ones being breakpointing and single-stepping kernel
code.</para>
<para>If you need to do low-level debugging on your kernel, there is
an on-line debugger available called DDB. It allows to setting
<para>If you need to do low-level debugging on your kernel, there is an
on-line debugger available called DDB. It allows to setting
breakpoints, single-steping kernel functions, examining and changing
kernel variables, etc. However, it cannot access kernel source
files, and only has access to the global and static symbols, not to
the full debug information like <command>kgdb</command>.</para>
kernel variables, etc. However, it cannot access kernel source files,
and only has access to the global and static symbols, not to the full
debug information like <command>kgdb</command>.</para>
<para>To configure your kernel to include DDB, add the option line
<programlisting>
options DDB</programlisting> to your config file, and rebuild. (See <link
linkend="kernelconfig">Kernel Configuration</link> for details on configuring the
FreeBSD kernel.</para>
options DDB</programlisting>
to your config file, and rebuild. (See <link
linkend="kernelconfig">Kernel Configuration</link> for details on
configuring the FreeBSD kernel.</para>
<note>
<para>Note that if you have an older version of the boot blocks,
your debugger symbols might not be loaded at all. Update the boot
blocks; the recent ones load the DDB symbols
automagically.)</para>
<para>Note that if you have an older version of the boot blocks, your
debugger symbols might not be loaded at all. Update the boot blocks;
the recent ones load the DDB symbols automagically.)</para>
</note>
<para>Once your DDB kernel is running, there are several ways to enter
DDB. The first, and earliest way is to type the boot flag
<option>-d</option> right at the boot prompt. The kernel will start
up in debug mode and enter DDB prior to any device probing. Hence
you can even debug the device probe/attach functions.</para>
<option>-d</option> right at the boot prompt. The kernel will start up
in debug mode and enter DDB prior to any device probing. Hence you can
even debug the device probe/attach functions.</para>
<para>The second scenario is a hot-key on the keyboard, usually
Ctrl-Alt-ESC. For syscons, this can be remapped; some of the
distributed maps do this, so watch out. There is an option available
for serial consoles that allows the use of a serial line BREAK on
the console line to enter DDB (<literal>options
BREAK_TO_DEBUGGER</literal> in the kernel config file). It is
not the default since there are a lot of crappy serial adapters
around that gratuitously generate a BREAK condition, for example
when pulling the cable.</para>
for serial consoles that allows the use of a serial line BREAK on the
console line to enter DDB (<literal>options BREAK_TO_DEBUGGER</literal>
in the kernel config file). It is not the default since there are a lot
of crappy serial adapters around that gratuitously generate a BREAK
condition, for example when pulling the cable.</para>
<para>The third way is that any panic condition will branch to DDB if
the kernel is configured to use it. For this reason, it is not
wise to configure a kernel with DDB for a machine running
unattended.</para>
<para>The DDB commands roughly resemble some <command>gdb</command> commands. The first thing you probably
need to do is to set a breakpoint:</para>
<para>The third way is that any panic condition will branch to DDB if the
kernel is configured to use it. For this reason, it is not wise to
configure a kernel with DDB for a machine running unattended.</para>
<para>The DDB commands roughly resemble some <command>gdb</command>
commands. The first thing you probably need to do is to set a
breakpoint:</para>
<screen><userinput>b function-name</userinput>
<userinput>b address</userinput></screen>
<para>Numbers are taken hexadecimal by default, but to make them distinct
from symbol names; hexadecimal numbers starting with the letters
<literal>a-f</literal> need to be preceded with <literal>0x</literal>
(this is optional for other numbers). Simple expressions are allowed,
for example: <literal>function-name + 0x103</literal>.</para>
<para>Numbers are taken hexadecimal by default, but to make them
distinct from symbol names; hexadecimal numbers starting with the
letters <literal>a-f</literal> need to be preceded with
<literal>0x</literal> (this is optional for other numbers). Simple
expressions are allowed, for example: <literal>function-name +
0x103</literal>.</para>
<para>To continue the operation of an interrupted kernel, simply type:</para>
<para>To continue the operation of an interrupted kernel, simply
type:</para>
<screen><userinput>c</userinput></screen>
<para>To get a stack trace, use:</para>
<screen><userinput>trace</userinput></screen>
<note>
<para>Note that when entering DDB via a hot-key, the kernel is
currently servicing an interrupt, so the stack trace might be not
of much use for you.</para>
<para>Note that when entering DDB via a hot-key, the kernel is currently
servicing an interrupt, so the stack trace might be not of much use
for you.</para>
</note>
<para>If you want to remove a breakpoint, use</para>
@ -381,178 +359,143 @@ options DDB</programlisting> to your config file, and rebuild. (See <link
<screen><userinput>del</userinput>
<userinput>del address-expression</userinput></screen>
<para>The first form will be accepted immediately after
a breakpoint hit, and deletes the current breakpoint. The second
form can remove any breakpoint, but you need to specify the exact
address; this can be obtained from:</para>
<para>The first form will be accepted immediately after a breakpoint hit,
and deletes the current breakpoint. The second form can remove any
breakpoint, but you need to specify the exact address; this can be
obtained from:</para>
<screen><userinput>show b</userinput></screen>
<para>To single-step the kernel, try:</para>
<screen><userinput>s</userinput></screen>
<para>This will step into functions, but you can make
DDB trace them until the matching return statement is reached by:</para>
<para>This will step into functions, but you can make DDB trace them until
the matching return statement is reached by:</para>
<screen><userinput>n</userinput></screen>
<note>
<para>This is different from <command>gdb</command>'s <command>next</command>
statement; it is like <command>gdb</command>'s <command>finish</command>.</para>
<para>This is different from <command>gdb</command>'s
<command>next</command> statement; it is like <command>gdb</command>'s
<command>finish</command>.</para>
</note>
<para>To examine data from memory, use (for example):
<screen><userinput>x/wx 0xf0133fe0,40</userinput>
<userinput>x/hd db_symtab_space</userinput>
<userinput>x/bc termbuf,10</userinput>
<userinput>x/s stringbuf</userinput></screen>
for word/halfword/byte access, and
hexadecimal/decimal/character/ string display. The number after the
comma is the object count. To display the next 0x10 items, simply
use:</para>
for word/halfword/byte access, and hexadecimal/decimal/character/ string
display. The number after the comma is the object count. To display
the next 0x10 items, simply use:</para>
<screen><userinput>x ,10</userinput></screen>
<para>Similarly, use
<screen><userinput>x/ia foofunc,10</userinput></screen>
to disassemble the first 0x10 instructions of
<function>foofunc</function>, and display them along with
their offset from the beginning of <function>foofunc</function>.</para>
<function>foofunc</function>, and display them along with their offset
from the beginning of <function>foofunc</function>.</para>
<para>To modify memory, use the write command:</para>
<screen><userinput>w/b termbuf 0xa 0xb 0</userinput>
<userinput>w/w 0xf0010030 0 0</userinput></screen>
<para>The command modifier
(<literal>b</literal>/<literal>h</literal>/<literal>w</literal>) specifies the size of the data to be
written, the first following expression is the address to write to
and the remainder is interpreted as data to write to successive
memory locations.</para>
(<literal>b</literal>/<literal>h</literal>/<literal>w</literal>)
specifies the size of the data to be written, the first following
expression is the address to write to and the remainder is interpreted
as data to write to successive memory locations.</para>
<para>If you need to know the current registers, use:</para>
<screen><userinput>show reg</userinput></screen>
<para>Alternatively, you can display a single register
value by e.g.
<para>Alternatively, you can display a single register value by e.g.
<screen><userinput>p $eax</userinput></screen>
and modify it by:</para>
<screen><userinput>set $eax new-value</userinput></screen>
<para>Should you need to call some kernel functions from DDB, simply
say:</para>
<screen><userinput>call func(arg1, arg2, ...)</userinput></screen>
<para>The return value will be printed.</para>
<para>For a &man.ps.1; style summary of all running
processes, use:</para>
<para>For a &man.ps.1; style summary of all running processes, use:</para>
<screen><userinput>ps</userinput></screen>
<para>Now you have now examined why your kernel failed, and you wish
to reboot. Remember that, depending on the severity of previous
malfunctioning, not all parts of the kernel might still be working
as expected. Perform one of the following actions to shut down and
reboot your system:</para>
<para>Now you have now examined why your kernel failed, and you wish to
reboot. Remember that, depending on the severity of previous
malfunctioning, not all parts of the kernel might still be working as
expected. Perform one of the following actions to shut down and reboot
your system:</para>
<screen><userinput>call diediedie()</userinput></screen>
<para>This will cause your kernel to dump core and reboot, so you can
later analyze the core on a higher level with kgdb. This command
usually must be followed by another <command>continue</command> statement. There is now an alias for
this: <command>panic</command>.</para>
usually must be followed by another <command>continue</command>
statement. There is now an alias for this:
<command>panic</command>.</para>
<screen><userinput>call boot(0)</userinput></screen>
<para>Which might be a good way to cleanly shut down the
running system, <function>sync()</function> all disks, and finally
reboot. As long as the disk and file system interfaces of the
kernel are not damaged, this might be a good way for an almost clean
shutdown.</para>
<para>Which might be a good way to cleanly shut down the running system,
<function>sync()</function> all disks, and finally reboot. As long as
the disk and file system interfaces of the kernel are not damaged, this
might be a good way for an almost clean shutdown.</para>
<screen><userinput>call cpu_reset()</userinput></screen>
<para>is the final way out of disaster and almost the
same as hitting the Big Red Button.</para>
<para>is the final way out of disaster and almost the same as hitting the
Big Red Button.</para>
<para>If you need a short command summary, simply type:</para>
<screen><userinput>help</userinput></screen>
<para>However, it is highly recommended to have a
printed copy of the &man.ddb.4; manual page
ready for a debugging session. Remember that it is hard to read the
on-line manual while single-stepping the kernel.</para>
<para>However, it is highly recommended to have a printed copy of the
&man.ddb.4; manual page ready for a debugging
session. Remember that it is hard to read the on-line manual while
single-stepping the kernel.</para>
</sect1>
<sect1>
<title>On-line Kernel Debugging Using Remote GDB</title>
<para>This feature has been supported since FreeBSD 2.2, and it's
actually a very neat one.</para>
<para>This feature has been supported since FreeBSD 2.2, and it's actually
a very neat one.</para>
<para>GDB has already supported <emphasis>remote debugging</emphasis>
for a long time. This is done using a very simple protocol along a
serial line. Unlike the other methods described above, you will
need two machines for doing this. One is the host providing the
debugging environment, including all the sources, and a copy of the
kernel binary with all the symbols in it, and the other one is the
target machine that simply runs a similar copy of the very same
kernel (but stripped of the debugging information).</para>
<para>GDB has already supported <emphasis>remote debugging</emphasis> for
a long time. This is done using a very simple protocol along a serial
line. Unlike the other methods described above, you will need two
machines for doing this. One is the host providing the debugging
environment, including all the sources, and a copy of the kernel binary
with all the symbols in it, and the other one is the target machine that
simply runs a similar copy of the very same kernel (but stripped of the
debugging information).</para>
<para>You should configure the kernel in question with <command>config
-g</command>, include <option>DDB</option> into the
configuration, and compile it as usual. This gives a large blurb of
a binary, due to the debugging information. Copy this kernel to the
target machine, strip the debugging symbols off with <command>strip
-x</command>, and boot it using the <option>-d</option> boot
option. Connect the first serial line of the target machine to any
serial line of the debugging host. Now, on the debugging machine,
go to the compile directory of the target kernel, and start gdb:</para>
-g</command>, include <option>DDB</option> into the configuration, and
compile it as usual. This gives a large blurb of a binary, due to the
debugging information. Copy this kernel to the target machine, strip
the debugging symbols off with <command>strip -x</command>, and boot it
using the <option>-d</option> boot option. Connect the first serial
line of the target machine to any serial line of the debugging host.
Now, on the debugging machine, go to the compile directory of the target
kernel, and start gdb:</para>
<screen>&prompt.user; <userinput>gdb -k kernel</userinput>
GDB is free software and you are welcome to distribute copies of it
@ -562,94 +505,77 @@ GDB 4.16 (i386-unknown-freebsd),
Copyright 1996 Free Software Foundation, Inc...
<prompt>(kgdb)</prompt> </screen>
<para>Initialize the remote debugging session (assuming the first
serial port is being used) by:</para>
<para>Initialize the remote debugging session (assuming the first serial
port is being used) by:</para>
<screen><prompt>(kgdb)</prompt> <userinput>target remote /dev/cuaa0</userinput></screen>
<para>Now, on the target host (the one that entered DDB right before
even starting the device probe), type:</para>
<para>Now, on the target host (the one that entered DDB right before even
starting the device probe), type:</para>
<screen>Debugger("Boot flags requested debugger")
Stopped at Debugger+0x35: movb $0, edata+0x51bc
<prompt>db&gt;</prompt> <userinput>gdb</userinput></screen>
<para>DDB will respond with:</para>
<screen>Next trap will enter GDB remote protocol mode</screen>
<para>Every time you type <command>gdb</command>, the mode will be toggled between
remote GDB and local DDB. In order to force a next trap
immediately, simply type <command>s</command> (step). Your hosting GDB will now
gain control over the target kernel:</para>
<para>Every time you type <command>gdb</command>, the mode will be toggled
between remote GDB and local DDB. In order to force a next trap
immediately, simply type <command>s</command> (step). Your hosting GDB
will now gain control over the target kernel:</para>
<screen>Remote debugging using /dev/cuaa0
Debugger (msg=0xf01b0383 "Boot flags requested debugger")
at ../../i386/i386/db_interface.c:257
<prompt>(kgdb)</prompt></screen>
<para>You can use this session almost as any other GDB session, including
full access to the source, running it in gud-mode inside an Emacs window
(which gives you an automatic source code display in another Emacs
window) etc.</para>
<para>You can use this session almost as any other GDB session,
including full access to the source, running it in gud-mode inside
an Emacs window (which gives you an automatic source code display in
another Emacs window) etc.</para>
<para>Remote GDB can also be used to debug LKMs. First build the LKM
with debugging symbols:</para>
<para>Remote GDB can also be used to debug LKMs. First build the LKM with
debugging symbols:</para>
<screen>&prompt.root; <userinput>cd /usr/src/lkm/linux</userinput>
&prompt.root; <userinput>make clean; make COPTS=-g</userinput></screen>
<para>Then install this version of the module on the target machine,
load it and use <command>modstat</command> to find out
where it was loaded:</para>
<para>Then install this version of the module on the target machine, load
it and use <command>modstat</command> to find out where it was
loaded:</para>
<screen>&prompt.root; <userinput>linux</userinput>
&prompt.root; <userinput>modstat</userinput>
Type Id Off Loadaddr Size Info Rev Module Name
EXEC 0 4 f5109000 001c f510f010 1 linux_mod</screen>
<para>Take the load address of the module and add 0x20 (probably to
account for the a.out header). This is the address that the module
code was relocated to. Use the <command>add-symbol-file</command> command in GDB to tell the
debugger about the module:</para>
account for the a.out header). This is the address that the module code
was relocated to. Use the <command>add-symbol-file</command> command in
GDB to tell the debugger about the module:</para>
<screen><prompt>(kgdb)</prompt> <userinput>add-symbol-file /usr/src/lkm/linux/linux_mod.o 0xf5109020</userinput>
add symbol table from file "/usr/src/lkm/linux/linux_mod.o" at
text_addr = 0xf5109020? (y or n) <userinput>y</userinput>
<prompt>(kgdb)</prompt></screen>
<para>You now have access to all the symbols in the LKM.</para>
</sect1>
<sect1>
<title>Debugging a Console Driver</title>
<para>Since you need a console driver to run DDB on, things are more
complicated if the console driver itself is failing. You might
remember the use of a serial console (either with modified boot
blocks, or by specifying <option>-h</option> at the <prompt>Boot:</prompt> prompt), and hook up a standard terminal
onto your first serial port. DDB works on any configured console
driver, of course also on a serial console.</para>
complicated if the console driver itself is failing. You might remember
the use of a serial console (either with modified boot blocks, or by
specifying <option>-h</option> at the <prompt>Boot:</prompt> prompt),
and hook up a standard terminal onto your first serial port. DDB works
on any configured console driver, of course also on a serial
console.</para>
</sect1>
</chapter>
</chapter>
<!--
Local Variables:

175
en/handbook/kernelopts/chapter.sgml
View file

@ -1,53 +1,50 @@
<chapter id="kernelopts">
<chapter id="kernelopts">
<title>Adding New Kernel Configuration Options</title>
<para><emphasis>Contributed by &a.joerg;</emphasis></para>
<note>
<para>You should be familiar with the section about <link
linkend="kernelconfig">kernel configuration</link>
before reading here.</para>
linkend="kernelconfig">kernel configuration</link> before reading
here.</para>
</note>
<sect1>
<title>What's a <emphasis>Kernel Option</emphasis>, Anyway?</title>
<para>The use of kernel options is basically described in the <link
linkend="kernelconfig-options">kernel configuration</link>
section. There's also an explanation of &ldquo;historic&rdquo; and
&ldquo;new-style&rdquo; options. The ultimate goal is to eventually turn all
the supported options in the kernel into new-style ones, so for
people who correctly did a <command>make depend</command>
in their kernel compile directory after running
&man.config.8;, the build process will automatically
pick up modified options, and only recompile those files where it is
necessary. Wiping out the old compile directory on each run of
&man.config.8; as it is still done now can then be
eliminated again.</para>
linkend="kernelconfig-options">kernel configuration</link> section.
There's also an explanation of &ldquo;historic&rdquo; and
&ldquo;new-style&rdquo; options. The ultimate goal is to eventually
turn all the supported options in the kernel into new-style ones, so for
people who correctly did a <command>make depend</command> in their
kernel compile directory after running
&man.config.8;, the build process will automatically pick up modified
options, and only recompile those files where it is necessary. Wiping
out the old compile directory on each run of &man.config.8; as it is
still done now can then be eliminated again.</para>
<para>Basically, a kernel option is nothing else than the definition
of a C preprocessor macro for the kernel compilation process. To
make the build truly optional, the corresponding part of the kernel
source (or kernel <filename>.h</filename> file) must be written with
the option concept in mind, i.e. the default must have been made
overridable by the config option. This is usually done with
something like:</para>
<para>Basically, a kernel option is nothing else than the definition of a
C preprocessor macro for the kernel compilation process. To make the
build truly optional, the corresponding part of the kernel source (or
kernel <filename>.h</filename> file) must be written with the option
concept in mind, i.e. the default must have been made overridable by the
config option. This is usually done with something like:</para>
<programlisting>
#ifndef THIS_OPTION
#define THIS_OPTION (some_default_value)
#endif /* THIS_OPTION */</programlisting>
<para>This way, an administrator mentioning another value for the
option in his config file will take the default out of effect, and
replace it with his new value. Clearly, the new value will be
substituted into the source code during the preprocessor run, so it
must be a valid C expression in whatever context the default value
would have been used.</para>
<para>This way, an administrator mentioning another value for the option
in his config file will take the default out of effect, and replace it
with his new value. Clearly, the new value will be substituted into the
source code during the preprocessor run, so it must be a valid C
expression in whatever context the default value would have been
used.</para>
<para>It is also possible to create value-less options that simply
enable or disable a particular piece of code by embracing it
in</para>
<para>It is also possible to create value-less options that simply enable
or disable a particular piece of code by embracing it in</para>
<programlisting>
#ifdef THAT_OPTION
@ -56,15 +53,14 @@
#endif</programlisting>
<para>Simply mentioning <literal>THAT_OPTION</literal> in the config
file (with or without any value) will then turn on the corresponding
piece of code.</para>
<para>Simply mentioning <literal>THAT_OPTION</literal> in the config file
(with or without any value) will then turn on the corresponding piece of
code.</para>
<para>People familiar with the C language will immediately recognize
that everything could be counted as a &ldquo;config option&rdquo; where there
is at least a single <literal>#ifdef</literal>
referencing it... However, it's unlikely that many people would
put</para>
<para>People familiar with the C language will immediately recognize that
everything could be counted as a &ldquo;config option&rdquo; where there
is at least a single <literal>#ifdef</literal> referencing it...
However, it's unlikely that many people would put</para>
<programlisting>
options notyet,notdef</programlisting>
@ -72,38 +68,40 @@ options notyet,notdef</programlisting>
<para>in their config file, and then wonder why the kernel compilation
falls over. <!-- smiley -->:-)</para>
<para>Clearly, using arbitrary names for the options makes it very
hard to track their usage throughout the kernel source tree. That
is the rationale behind the <emphasis>new-style</emphasis> option
scheme, where each option goes into a separate
<filename>.h</filename> file in the kernel compile directory, which
is by convention named
<para>Clearly, using arbitrary names for the options makes it very hard to
track their usage throughout the kernel source tree. That is the
rationale behind the <emphasis>new-style</emphasis> option scheme, where
each option goes into a separate <filename>.h</filename> file in the
kernel compile directory, which is by convention named
<filename>opt_<replaceable>foo</replaceable>.h</filename>. This way,
the usual Makefile dependencies could be applied, and <command>make</command> can determine what needs to be recompiled
once an option has been changed.</para>
the usual Makefile dependencies could be applied, and
<command>make</command> can determine what needs to be recompiled once
an option has been changed.</para>
<para>The old-style option mechanism still has one advantage for local
options or maybe experimental options that have a short anticipated
lifetime: since it is easy to add a new <literal>#ifdef</literal> to the kernel source, this has already
made it a kernel config option. In this case, the administrator
using such an option is responsible himself for knowing about its
implications (and maybe manually forcing the recompilation of parts
of his kernel). Once the transition of all supported options has
been done, &man.config.8; will warn whenever an
unsupported option appears in the config file, but it will
nevertheless include it into the kernel Makefile.</para>
lifetime: since it is easy to add a new <literal>#ifdef</literal> to the
kernel source, this has already made it a kernel config option. In this
case, the administrator using such an option is responsible himself for
knowing about its implications (and maybe manually forcing the
recompilation of parts of his kernel). Once the transition of all
supported options has been done, &man.config.8; will warn whenever an
unsupported option appears in the config file, but it will nevertheless
include it into the kernel Makefile.</para>
</sect1>
<sect1>
<title>Now What Do I Have to Do for it?</title>
<para>First, edit <filename>sys/conf/options</filename> (or
<filename>sys/i386/conf/options.<replaceable>&lt;arch&gt;</replaceable></filename>, e. g. <filename>sys/i386/conf/options.i386</filename>), and select an <filename>opt_<replaceable>foo</replaceable>.h</filename> file where your new option would best go into.</para>
<filename>sys/i386/conf/options.<replaceable>&lt;arch&gt;</replaceable></filename>,
e. g. <filename>sys/i386/conf/options.i386</filename>), and select an
<filename>opt_<replaceable>foo</replaceable>.h</filename> file where
your new option would best go into.</para>
<para>If there is already something that comes close to the purpose of
the new option, pick this. For example, options modifying the
overall behaviour of the SCSI subsystem can go into
<para>If there is already something that comes close to the purpose of the
new option, pick this. For example, options modifying the overall
behaviour of the SCSI subsystem can go into
<filename>opt_scsi.h</filename>. By default, simply mentioning an
option in the appropriate option file, say <literal>FOO</literal>,
implies its value will go into the corresponding file
@ -114,51 +112,38 @@ options notyet,notdef</programlisting>
<filename>opt_<replaceable>foo</replaceable>.h</filename> already
available for the intended new option, invent a new name. Make it
meaningful, and comment the new section in the
<filename>options[<replaceable>.&lt;arch&gt;</replaceable>]</filename> file. &man.config.8; will automagically pick up the change, and create that file next time it is run. Most options should go in a header file by themselves..</para>
<filename>options[<replaceable>.&lt;arch&gt;</replaceable>]</filename>
file. &man.config.8; will automagically pick up the change, and create
that file next time it is run. Most options should go in a header file
by themselves..</para>
<para>Packing too many options into a single
<filename>opt_<replaceable>foo</replaceable>.h</filename> will cause
too many kernel files to be rebuilt when one of the options has been
changed in the config file.</para>
<filename>opt_<replaceable>foo</replaceable>.h</filename> will cause too
many kernel files to be rebuilt when one of the options has been changed
in the config file.</para>
<para>Finally, find out which kernel files depend on the new option.
Unless you have just invented your option, and it does not exist
anywhere yet,
anywhere yet, <screen>&prompt.user; <userinput>find /usr/src/sys -name
type f | xargs fgrep NEW_OPTION</userinput></screen> is your friend
in finding them. Go and edit all those files, and add <programlisting>
#include "opt_foo.h"</programlisting> <emphasis>on top</emphasis>,
before all the <literal>#include &lt;xxx.h&gt;</literal> stuff. This
sequence is most important as the options could override defaults from
the regular include files, if the defaults are of the form
<programlisting> #ifndef NEW_OPTION #define NEW_OPTION (something)
#endif</programlisting> in the regular header.</para>
<screen>&prompt.user; <userinput>find /usr/src/sys -name type f | xargs fgrep NEW_OPTION</userinput></screen>
is your friend in finding them. Go and edit all those files,
and add
<programlisting>
#include "opt_foo.h"</programlisting>
<emphasis>on top</emphasis>, before all the <literal>#include &lt;xxx.h&gt;</literal> stuff. This sequence
is most important as the options could override defaults from the
regular include files, if the defaults are of the form
<programlisting>
#ifndef NEW_OPTION
#define NEW_OPTION (something)
#endif</programlisting>
in the regular header.</para>
<para>Adding an option that overrides something in a system header
file (i.e., a file sitting in
<filename>/usr/include/sys/</filename>) is almost always a mistake.
<para>Adding an option that overrides something in a system header file
(i.e., a file sitting in <filename>/usr/include/sys/</filename>) is
almost always a mistake.
<filename>opt_<replaceable>foo</replaceable>.h</filename> cannot be
included into those files since it would break the headers more
seriously, but if it is not included, then places that include it
may get an inconsistent value for the option. Yes, there are
precedents for this right now, but that does not make them more
correct.</para>
seriously, but if it is not included, then places that include it may
get an inconsistent value for the option. Yes, there are precedents for
this right now, but that does not make them more correct.</para>
</sect1>
</chapter>
</chapter>
<!--
Local Variables:

221
en/handbook/l10n/chapter.sgml
View file

@ -1,7 +1,6 @@
<chapter id="l10n">
<chapter id="l10n">
<title>Localization</title>
<sect1 id="russian">
<title>Russian Language (KOI8-R encoding)</title>
@ -12,20 +11,18 @@
URL="http://www.nagual.pp.ru/~ache/koi8.html">KOI8-R References
(Russian Net Character Set)</ulink>.</para>
<sect2 id="russian-console">
<title>Console Setup</title>
<procedure>
<step>
<para>Add following line to your kernel configuration file:
<programlisting>
options "SC_MOUSE_CHAR=0x03"</programlisting> to move character
codes used for mouse cursor off KOI8-R pseudographics
range.</para>
options "SC_MOUSE_CHAR=0x03"</programlisting>
to move character codes used for mouse cursor off KOI8-R
pseudographics range.</para>
</step>
<step>
@ -42,35 +39,31 @@ font8x8=cp866-8x8</programlisting>
<note>
<para>^[ means that real ESC character must be entered into
<filename>/etc/rc.conf</filename>, not just ^[
string.</para>
<filename>/etc/rc.conf</filename>, not just ^[ string.</para>
</note>
<para>This tuning means KOI8-R keyboard with Alternative
screen font mapped to KOI8-R encoding to preserve
pseudographics, <literal>Gray Delete</literal>
key remapped to match Russian &man.termcap.5; entry for FreeBSD
console.</para>
<para>This tuning means KOI8-R keyboard with Alternative screen font
mapped to KOI8-R encoding to preserve pseudographics,
<literal>Gray Delete</literal> key remapped to match Russian
&man.termcap.5; entry for
FreeBSD console.</para>
<para>RUS/LAT switch will be <literal>CapsLock</literal>. Old CapsLock function still
available via <literal>Shift+CapsLock</literal>.
CapsLock LED will indicate RUS mode, not CapsLock
mode.</para>
<para>RUS/LAT switch will be <literal>CapsLock</literal>. Old
CapsLock function still available via
<literal>Shift+CapsLock</literal>. CapsLock LED will indicate RUS
mode, not CapsLock mode.</para>
</step>
<step>
<para>For each <literal>ttyv?</literal> entry in
<filename>/etc/ttys</filename> change terminal type from
<literal>cons25</literal> to <literal>cons25r</literal>, i.e. each entry should looks
like:</para>
<literal>cons25</literal> to <literal>cons25r</literal>, i.e. each
entry should looks like:</para>
<programlisting>
ttyv0 "/usr/libexec/getty Pc" cons25r on secure</programlisting>
</step>
</procedure>
</sect2>
<sect2 id="russian-locale">
@ -80,32 +73,28 @@ ttyv0 "/usr/libexec/getty Pc" cons25r on secure</programlisting>
for locale setup:</para>
<itemizedlist>
<listitem>
<para><envar>LANG</envar> for POSIX
&man.setlocale.3; family functions;</para>
<para><envar>LANG</envar> for POSIX &man.setlocale.3; family
functions;</para>
</listitem>
<listitem>
<para><envar>MM_CHARSET</envar> for applications MIME
chararter set.</para>
<para><envar>MM_CHARSET</envar> for applications MIME chararter
set.</para>
</listitem>
</itemizedlist>
<para>The best way is using <filename>/etc/login.conf</filename>
<literal>russian</literal> user's login class in
&man.passwd.5; entry login class
position. See &man.login.conf.5; for
details.</para>
&man.passwd.5; entry login class position. See &man.login.conf.5;
for details.</para>
<sect3 id="russian-class">
<title>Login Class Method</title>
<para>First of all check your <filename>/etc/login.conf</filename>
have <literal>russian</literal> login class, this
entry may looks like:</para>
have <literal>russian</literal> login class, this entry may looks
like:</para>
<programlisting>
russian:Russian Users Accounts:\
@ -113,82 +102,71 @@ russian:Russian Users Accounts:\
:lang=ru_RU.KOI8-R:\
:tc=default:</programlisting>
<sect4>
<title>How to do it with &man.vipw.8;</title>
<para>If you use &man.vipw.8; for adding new
users, <filename>/etc/master.passwd</filename> entry should
looks like:</para>
<para>If you use &man.vipw.8; for adding new users,
<filename>/etc/master.passwd</filename> entry should looks
like:</para>
<programlisting>
user:password:1111:11:russian:0:0:User Name:/home/user:/bin/csh</programlisting>
</sect4>
<sect4>
<title>How to do it with &man.adduser.8;</title>
<para>If you use &man.adduser.8; for adding new
users:</para>
<itemizedlist>
<para>If you use &man.adduser.8; for adding new users:</para>
<itemizedlist>
<listitem>
<para>Set
<programlisting>
defaultclass = russian</programlisting> in
<filename>/etc/adduser.conf</filename> (you must enter
<literal>default</literal> class for all
non-Russian users in this case);</para>
defaultclass = russian</programlisting>
in <filename>/etc/adduser.conf</filename> (you must enter
<literal>default</literal> class for all non-Russian users in
this case);</para>
</listitem>
<listitem>
<para>Alternative variant will be answering <literal>russian</literal> each time when you see
<para>Alternative variant will be answering
<literal>russian</literal> each time when you see
<screen><prompt>Enter login class:</prompt> default []:</screen>
prompt from
&man.adduser.8;;</para>
prompt from &man.adduser.8;;</para>
</listitem>
<listitem>
<para>Another variant: call
<screen>&prompt.root; <userinput>adduser -class russian</userinput></screen>
for each Russian user
you want to add.</para>
for each Russian user you want to add.</para>
</listitem>
</itemizedlist>
</sect4>
<sect4>
<title>How to do it with &man.pw.8;</title>
<para>If you use &man.pw.8; for adding new users,
call it in this form:</para>
<para>If you use &man.pw.8; for adding new users, call it in this
form:</para>
<screen>&prompt.root; <userinput>pw useradd user_name -L russian</userinput></screen>
</sect4>
</sect3>
<sect3>
<title>Shell Startup Files Method</title>
<para>If you don't want to use
<link linkend="russian-class">login class method</link> for
some reasons, just set this
<link linkend="russian-env">two environment variables</link>
in the following shell startup files:</para>
<para>If you don't want to use <link linkend="russian-class">login
class method</link> for some reasons, just set this <link
linkend="russian-env">two environment variables</link> in the
following shell startup files:</para>
<itemizedlist>
<listitem>
<para><filename>/etc/profile</filename>:</para>
@ -204,18 +182,15 @@ MM_CHARSET=KOI8-R; export MM_CHARSET</programlisting>
setenv LANG ru_RU.KOI8-R
setenv MM_CHARSET KOI8-R</programlisting>
</listitem>
</itemizedlist>
<para>Alternatively you can add this instructions to</para>
<itemizedlist>
<itemizedlist>
<listitem>
<para><filename>/usr/share/skel/dot.profile</filename>:</para>
<para>(similar to <filename>/etc/profile</filename>
above);</para>
<para>(similar to <filename>/etc/profile</filename> above);</para>
</listitem>
<listitem>
@ -224,21 +199,18 @@ setenv MM_CHARSET KOI8-R</programlisting>
<para>(similar to <filename>/etc/csh.login</filename>
above).</para>
</listitem>
</itemizedlist>
</sect3>
</sect2>
<sect2 id="russian-printer">
<title>Printer Setup</title>
<para>Since most printers with Russian characters comes with
hardware code page CP866, special output filter needed for KOI8-R
-&gt; CP866 conversion. Such filter installed by default as
<filename>/usr/libexec/lpr/ru/koi2alt</filename>. So, Russian
printer <filename>/etc/printcap</filename> entry should looks
like:</para>
<para>Since most printers with Russian characters comes with hardware
code page CP866, special output filter needed for KOI8-R -&gt; CP866
conversion. Such filter installed by default as
<filename>/usr/libexec/lpr/ru/koi2alt</filename>. So, Russian printer
<filename>/etc/printcap</filename> entry should looks like:</para>
<programlisting>
lp|Russian local line printer:\
@ -246,22 +218,19 @@ lp|Russian local line printer:\
:lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs:</programlisting>
<para>See &man.printcap.5; for detailed description.</para>
</sect2>
<sect2 id="russian-msdosfs">
<title>MSDOS FS and Russian file names</title>
<para>Look at following example &man.fstab.5; entry to enable support for Russian
file names in MSDOS FS:</para>
<para>Look at following example &man.fstab.5; entry to enable support
for Russian file names in MSDOS FS:</para>
<programlisting>
/dev/sd0s1 /dos/c msdos rw,-W=koi2dos,-L=ru_RU.KOI8-R 0 0</programlisting>
<para>See
&man.mount.msdos.8; for detailed description of
<para>See &man.mount.msdos.8; for detailed description of
<option>-W</option> and <option>-L</option> options.</para>
</sect2>
<sect2 id="russian-xwindow">
@ -270,22 +239,18 @@ lp|Russian local line printer:\
<para>Step by step instructions:</para>
<procedure>
<step>
<para>Do
<link linkend="russian-locale">non-X locale setup</link>
<para>Do <link linkend="russian-locale">non-X locale setup</link>
first as described.</para>
<note>
<para><anchor id="russian-note">Russian KOI8-R locale may
not work with old XFree86 releases (lower than 3.3).
XFree86 port from
<filename>/usr/ports/x11/XFree86</filename> already have
most recent XFree86 version, so it will work, if you
install XFree86 from this port. XFree86 version shipped
with the latest FreeBSD distribution should work too
(check XFree86 version number not less than 3.3
first).</para>
<para><anchor id="russian-note">Russian KOI8-R locale may not work
with old XFree86 releases (lower than 3.3). XFree86 port from
<filename>/usr/ports/x11/XFree86</filename> already have most
recent XFree86 version, so it will work, if you install XFree86
from this port. XFree86 version shipped with the latest FreeBSD
distribution should work too (check XFree86 version number not
less than 3.3 first).</para>
</note>
</step>
@ -293,63 +258,61 @@ lp|Russian local line printer:\
<para>Go to <filename>/usr/ports/russian/X.language</filename>
directory and say
<screen>&prompt.root; <userinput>make all install</userinput></screen>
there. This port install latest
version of KOI8-R fonts. XFree86 3.3 already have some
KOI8-R fonts, but this ones scaled better.</para>
there. This port install latest version of KOI8-R fonts. XFree86
3.3 already have some KOI8-R fonts, but this ones scaled
better.</para>
<para>Check find <literal>"Files"</literal> section
in your <filename>/etc/XF86Config</filename>, following
lines must be before any other <literal>FontPath</literal>
entries:</para>
<para>Check find <literal>"Files"</literal> section in your
<filename>/etc/XF86Config</filename>, following lines must be
before any other <literal>FontPath</literal> entries:</para>
<programlisting>
FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/misc"
FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/75dpi"
FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/100dpi"</programlisting>
<para>If you use high resolution video mode, swap 75 dpi and
100 dpi lines.</para>
<para>If you use high resolution video mode, swap 75 dpi and 100 dpi
lines.</para>
</step>
<step>
<para>To activate Russian keyboard add
<programlisting>
XkbKeymap "xfree86(ru)"</programlisting> line into
<literal>"Keyboard"</literal> section in your
<filename>/etc/XF86Config</filename>, also make sure that
<literal>XkbDisable</literal> is turned off
(commented out) there.</para>
XkbKeymap "xfree86(ru)"</programlisting>
<para>RUS/LAT switch will be <literal>CapsLock</literal>. Old CapsLock function still
available via <literal>Shift+CapsLock</literal>
(in LAT mode only).</para>
line into <literal>"Keyboard"</literal> section in your
<filename>/etc/XF86Config</filename>, also make sure that
<literal>XkbDisable</literal> is turned off (commented out)
there.</para>
<para>RUS/LAT switch will be <literal>CapsLock</literal>. Old
CapsLock function still available via
<literal>Shift+CapsLock</literal> (in LAT mode only).</para>
<note>
<para>Russian XKB keyboard may not work with old XFree86
versions, see <link
linkend="russian-note">locale note</link> for more info.
Russian XKB keyboard may not work with non-localized
applications too, minimally localized application should
call <literal>XtSetLanguageProc
(NULL, NULL, NULL);</literal> function early in the program.</para>
<para>Russian XKB keyboard may not work with old XFree86 versions,
see <link linkend="russian-note">locale note</link> for more
info. Russian XKB keyboard may not work with non-localized
applications too, minimally localized application should call
<literal>XtSetLanguageProc (NULL, NULL, NULL);</literal>
function early in the program.</para>
</note>
</step>
</procedure>
</sect2>
</sect1>
<sect1 id="german">
<title>German Language (ISO 8859-1)</title>
<para>Slaven Rezic <email>eserte@cs.tu-berlin.de</email> wrote a tutorial how to use umlauts on a FreeBSD machine. The tutorial is written in German and available at <ulink URL="http://www.de.freebsd.org/de/umlaute/">http://www.de.freebsd.org/de/umlaute/</ulink>.</para>
<para>Slaven Rezic <email>eserte@cs.tu-berlin.de</email> wrote a tutorial
how to use umlauts on a FreeBSD machine. The tutorial is written in
German and available at <ulink
URL="http://www.de.freebsd.org/de/umlaute/">http://www.de.freebsd.org/de/umlaute/</ulink>.</para>
</sect1>
</chapter>
</chapter>
<!--
Local Variables:

760
en/handbook/linuxemu/chapter.sgml
View file

File diff suppressed because it is too large Load diff

466
en/handbook/mail/chapter.sgml
View file

@ -1,37 +1,34 @@
<chapter id="mail">
<chapter id="mail">
<title>Electronic Mail</title>
<para><emphasis>Contributed by &a.wlloyd;.</emphasis></para>
<para>Electronic Mail configuration is the subject of many <link
linkend="bibliography">System Administration</link> books. If you
plan on doing anything beyond setting up one mailhost for your
network, you need industrial strength help.</para>
<para>Some parts of E-Mail configuration are controlled in the Domain
Name System (DNS). If you are going to run your own own DNS server
check out <filename>/etc/namedb</filename> and <command>man -k named</command> for more information.</para>
linkend="bibliography">System Administration</link> books. If you plan
on doing anything beyond setting up one mailhost for your network, you
need industrial strength help.</para>
<para>Some parts of E-Mail configuration are controlled in the Domain Name
System (DNS). If you are going to run your own own DNS server check out
<filename>/etc/namedb</filename> and <command>man -k named</command> for
more information.</para>
<sect1>
<title>Basic Information</title>
<para>These are the major programs involved in an E-Mail exchange. A
&ldquo;mailhost&rdquo; is a server that is
responsible for delivering and receiving all email for your host,
and possibly your network.</para>
&ldquo;mailhost&rdquo; is a server that is responsible for delivering
and receiving all email for your host, and possibly your network.</para>
<sect2>
<title>User program</title>
<para>This is a program like <application >elm</application>, <application>pine</application>,
<application>mail</application>, or something more sophisticated like a WWW
browser. This program will simply pass off all e-mail
transactions to the local &ldquo;mailhost&rdquo; ,
either by calling <command>sendmail</command> or
delivering it over TCP.</para>
<para>This is a program like <application >elm</application>,
<application>pine</application>, <application>mail</application>, or
something more sophisticated like a WWW browser. This program will
simply pass off all e-mail transactions to the local
&ldquo;mailhost&rdquo; , either by calling <command>sendmail</command>
or delivering it over TCP.</para>
</sect2>
<sect2>
@ -39,150 +36,137 @@
<para>Usually this program is <command>sendmail</command> or
<command>smail</command> running in the background. Turn it off or
change the command line options in
<filename>/etc/rc.conf</filename> (or, prior to FreeBSD 2.2.2,
<filename>/etc/sysconfig</filename>). It is best to leave it on,
unless you have a specific reason to want it off. Example: You
are building a <link
change the command line options in <filename>/etc/rc.conf</filename>
(or, prior to FreeBSD 2.2.2, <filename>/etc/sysconfig</filename>). It
is best to leave it on, unless you have a specific reason to want it
off. Example: You are building a <link
linkend="firewalls">Firewall</link>.</para>
<para>You should be aware that <command>sendmail</command> is a potential weak link in a
secure site. Some versions of <command>sendmail</command> have known security
problems.</para>
<para>You should be aware that <command>sendmail</command> is a
potential weak link in a secure site. Some versions of
<command>sendmail</command> have known security problems.</para>
<para><command>sendmail</command> does two jobs. It looks after delivering
and receiving mail.</para>
<para><command>sendmail</command> does two jobs. It looks after
delivering and receiving mail.</para>
<para>If <command>sendmail</command>
needs to deliver mail off your site it will look up in
the DNS to determine the actual host that will receive mail for
the destination.</para>
<para>If it is acting as a delivery agent <command>sendmail</command> will take the message from the
local queue and deliver it across the Internet to another sendmail
on the receivers computer.</para>
<para>If <command>sendmail</command> needs to deliver mail off your site
it will look up in the DNS to determine the actual host that will
receive mail for the destination.</para>
<para>If it is acting as a delivery agent <command>sendmail</command>
will take the message from the local queue and deliver it across the
Internet to another sendmail on the receivers computer.</para>
</sect2>
<sect2>
<title>DNS &mdash; Name Service</title>
<para>The Domain Name System and its daemon <command>named</command>, contain the database mapping
hostname to IP address, and hostname to mailhost. The IP address
is specified in an A record. The MX record specifies the
mailhost that will receive mail for you. If you do not have a
MX record mail for your hostname, the mail will be delivered to
<para>The Domain Name System and its daemon <command>named</command>,
contain the database mapping hostname to IP address, and hostname to
mailhost. The IP address is specified in an A record. The MX record
specifies the mailhost that will receive mail for you. If you do not
have a MX record mail for your hostname, the mail will be delivered to
your host directly.</para>
<para>Unless you are running your own DNS server, you will not be
able to change any information in the DNS yourself. If you are
using an Internet Provider, speak to them.</para>
<para>Unless you are running your own DNS server, you will not be able
to change any information in the DNS yourself. If you are using an
Internet Provider, speak to them.</para>
</sect2>
<sect2>
<title>POP Servers</title>
<para>This program gets the mail from your mailbox and gives it to
your browser. If you want to run a POP server on your computer,
you will need to do 2 things.</para>
<para>This program gets the mail from your mailbox and gives it to your
browser. If you want to run a POP server on your computer, you will
need to do 2 things.</para>
<procedure>
<step>
<para>Get pop software from the <ulink
URL="../ports/mail.html">Ports collection</ulink> that
can be found in <filename>/usr/ports</filename> or packages
collection. This handbook section has a complete reference
on the <link linkend="ports">Ports</link> system.</para>
URL="../ports/mail.html">Ports collection</ulink> that can be
found in <filename>/usr/ports</filename> or packages collection.
This handbook section has a complete reference on the <link
linkend="ports">Ports</link> system.</para>
</step>
<step>
<para>Modify <filename>/etc/inetd.conf</filename>
to load the POP server.</para>
<para>Modify <filename>/etc/inetd.conf</filename> to load the POP
server.</para>
</step>
</procedure>
<para>The pop program will have instructions with it. Read
them.</para>
<para>The pop program will have instructions with it. Read them.</para>
</sect2>
</sect1>
<sect1>
<title>Configuration</title>
<sect2>
<title>Basic</title>
<para>As your FreeBSD system comes &ldquo;out of the box&rdquo;[TM], you should
be able to send E-mail to external hosts as long as you have
<para>As your FreeBSD system comes &ldquo;out of the box&rdquo;[TM], you
should be able to send E-mail to external hosts as long as you have
<filename>/etc/resolv.conf</filename> setup or are running a name
server. If you want to have mail for your host delivered to your
specific host,there are two methods:</para>
<itemizedlist>
<listitem>
<para>Run a name server (<command>man -k named</command>) and have your own domain
<hostid role="domainname">smallminingco.com </hostid></para>
<para>Run a name server (<command>man -k named</command>) and have
your own domain <hostid role="domainname">smallminingco.com
</hostid></para>
</listitem>
<listitem>
<para>Get mail delivered to the current DNS name for your host.
Ie: <hostid role="fqdn">dorm6.ahouse.school.edu </hostid></para>
<para>Get mail delivered to the current DNS name for your host. Ie:
<hostid role="fqdn">dorm6.ahouse.school.edu </hostid></para>
</listitem>
</itemizedlist>
<para>No matter what option you choose, to have mail delivered
directly to your host, you must be a full Internet host. You must
have a permanent IP address. IE: NO dynamic PPP. If you are
behind a firewall, the firewall must be passing on smtp traffic to
you. From <filename>/etc/services</filename>:</para>
<para>No matter what option you choose, to have mail delivered directly
to your host, you must be a full Internet host. You must have a
permanent IP address. IE: NO dynamic PPP. If you are behind a
firewall, the firewall must be passing on smtp traffic to you. From
<filename>/etc/services</filename>:</para>
<programlisting
>smtp 25/tcp mail #Simple Mail Transfer</programlisting>
<programlisting>
smtp 25/tcp mail #Simple Mail Transfer</programlisting>
<para>If you
want to receive mail at your host itself, you must make sure that
the DNS MX entry points to your host address, or there is no MX
entry for your DNS name.</para>
<para>If you want to receive mail at your host itself, you must make
sure that the DNS MX entry points to your host address, or there is no
MX entry for your DNS name.</para>
<para>Try this:</para>
<screen>&prompt.root; <userinput>hostname</userinput>
newbsdbox.freebsd.org
&prompt.root; <userinput>host newbsdbox.freebsd.org</userinput>
newbsdbox.freebsd.org has address 204.216.27.xx</screen>
<para>If that is all that comes out for your machine, mail directory
to <email>root@newbsdbox.freebsd.org</email>
will work no problems.</para>
<para>If that is all that comes out for your machine, mail directory to
<email>root@newbsdbox.freebsd.org</email> will work no
problems.</para>
<para>If instead, you have this:</para>
<screen>&prompt.root; <userinput>host newbsdbox.freebsd.org</userinput>
newbsdbox.FreeBSD.org has address 204.216.27.xx
newbsdbox.FreeBSD.org mail is handled (pri=10) by freefall.FreeBSD.org</screen>
<para>All mail sent to your host directly will end up on
<hostid>freefall</hostid>, under the same username.</para>
<para>All mail sent to your host
directly will end up on <hostid>freefall</hostid>, under the same username.</para>
<para>This information is setup in your domain name server. This should
be the same host that is listed as your primary nameserver in
<filename>/etc/resolv.conf</filename></para>
<para>This information is setup in your domain name server. This
should be the same host that is listed as your primary nameserver
in <filename>/etc/resolv.conf</filename></para>
<para>The DNS record that carries mail routing information is the Mail
eXchange entry. If no MX entry exists, mail will be delivered directly
to the host by way of the Address record.</para>
<para>The DNS record that carries mail routing information is the
Mail eXchange entry. If no MX entry exists, mail will be
delivered directly to the host by way of the Address
record.</para>
<para>The MX entry for <hostid role="fqdn">freefall.freebsd.org</hostid> at one time.</para>
<para>The MX entry for <hostid role="fqdn">freefall.freebsd.org</hostid>
at one time.</para>
<programlisting>
freefall MX 30 mail.crl.net
@ -193,39 +177,38 @@ freefall MX 20 who.cdrom.com
freefall A 204.216.27.xx
freefall CNAME www.FreeBSD.org</programlisting>
<para><hostid>freefall</hostid> has many MX entries. The lowest MX number gets the
mail in the end. The others will queue mail temporarily, if
<hostid>freefall</hostid> is busy or down.</para>
<para><hostid>freefall</hostid> has many MX entries. The lowest MX
number gets the mail in the end. The others will queue mail
temporarily, if <hostid>freefall</hostid> is busy or down.</para>
<para>Alternate MX sites should have separate connections to the
Internet, to be most useful. An Internet Provider or other
friendly site can provide this service.</para>
<para><command>dig</command>, <command>nslookup</command>,
and <command>host</command> are your friends.</para>
Internet, to be most useful. An Internet Provider or other friendly
site can provide this service.</para>
<para><command>dig</command>, <command>nslookup</command>, and
<command>host</command> are your friends.</para>
</sect2>
<sect2 id="mail-domain">
<title>Mail for your Domain (Network).</title>
<para>To setup up a network mailhost, you need to direct the mail
from arriving at all the workstations. In other words, you want to
hijack all mail for <hostid role="domainname">*.smallminingco.com
</hostid> and divert it to one machine, your &ldquo;mailhost&rdquo;.</para>
<para>To setup up a network mailhost, you need to direct the mail from
arriving at all the workstations. In other words, you want to hijack
all mail for <hostid role="domainname">*.smallminingco.com </hostid>
and divert it to one machine, your &ldquo;mailhost&rdquo;.</para>
<para>The network users on their workstations will most likely pick
up their mail over POP or telnet.</para>
<para>The network users on their workstations will most likely pick up
their mail over POP or telnet.</para>
<para>A user account with the <emphasis>same username</emphasis> should exist on both
machines. Please use <command>adduser</command> to do
<para>A user account with the <emphasis>same username</emphasis> should
exist on both machines. Please use <command>adduser</command> to do
this as required. If you set the <literal>shell</literal> to
<literal>/nonexistent</literal>
the user will not be allowed to login.</para>
<literal>/nonexistent</literal> the user will not be allowed to
login.</para>
<para>The mailhost that you will be using must be designated the
Mail eXchange for each workstation. This must be arranged in DNS
(ie BIND, named). Please refer to a Networking book for in-depth
Mail eXchange for each workstation. This must be arranged in DNS (ie
BIND, named). Please refer to a Networking book for in-depth
information.</para>
<para>You basically need to add these lines in your DNS server.</para>
@ -234,44 +217,45 @@ freefall CNAME www.FreeBSD.org</programlisting>
pc24.smallminingco.com A <replaceable>xxx.xxx.xxx.xxx</replaceable> ; Workstation ip
MX 10 smtp.smallminingco.com ; Your mailhost</programlisting>
<para>You cannot do this yourself unless you are running a DNS
server. If you do not want to run a DNS server, get somebody else
like your Internet Provider to do it.</para>
<para>You cannot do this yourself unless you are running a DNS server.
If you do not want to run a DNS server, get somebody else like your
Internet Provider to do it.</para>
<para>This will redirect mail for the workstation to the Mail
eXchange host. It does not matter what machine the A record
points to, the mail will be sent to the MX host.</para>
<para>This will redirect mail for the workstation to the Mail eXchange
host. It does not matter what machine the A record points to, the mail
will be sent to the MX host.</para>
<para>This feature is used to implement Virtual E-Mail Hosting.</para>
<para>Example</para>
<para>I have a customer with domain foo.bar and I want all mail for
foo.bar to be sent to my machine smtp.smalliap.com. You must make
an entry in your DNS server like:</para>
foo.bar to be sent to my machine smtp.smalliap.com. You must make an
entry in your DNS server like:</para>
<programlisting>
foo.bar MX 10 smtp.smalliap.com ; your mailhost</programlisting>
<para>The A record is not needed if you only
want E-Mail for the domain. IE: Don't expect <command>ping foo.bar</command>
to work unless an Address record for <filename>foo.bar</filename>
exists as well.</para>
<para>The A record is not needed if you only want E-Mail for the domain.
IE: Don't expect <command>ping foo.bar</command> to work unless an
Address record for <filename>foo.bar</filename> exists as well.</para>
<para>On the mailhost that actually accepts mail for final delivery
to a mailbox, <command>sendmail</command> must be told what hosts it will be
accepting mail for.</para>
<para>On the mailhost that actually accepts mail for final delivery to a
mailbox, <command>sendmail</command> must be told what hosts it will
be accepting mail for.</para>
<para>Add <literal>pc24.smallminingco.com</literal> to <filename>/etc/sendmail.cw</filename> (if you are
using <literal>FEATURE(use_cw_file)</literal>), or add a <literal>Cw myhost.smalliap.com</literal>
line to <filename>/etc/sendmail.cf</filename></para>
<para>If you plan on doing anything serious with <command>sendmail</command> you should install the <command>sendmail</command>
source. The source has plenty of documentation with it. You will
find information on getting <command>sendmail</command>
source from <link linkend="sendmailuucp">the UUCP
information</link>.</para>
<para>Add <literal>pc24.smallminingco.com</literal> to
<filename>/etc/sendmail.cw</filename> (if you are using
<literal>FEATURE(use_cw_file)</literal>), or add a <literal>Cw
myhost.smalliap.com</literal> line to
<filename>/etc/sendmail.cf</filename></para>
<para>If you plan on doing anything serious with
<command>sendmail</command> you should install the
<command>sendmail</command> source. The source has plenty of
documentation with it. You will find information on getting
<command>sendmail</command> source from <link
linkend="sendmailuucp">the UUCP information</link>.</para>
</sect2>
<sect2 id="sendmailuucp">
@ -279,65 +263,56 @@ foo.bar MX 10 smtp.smalliap.com ; your mailhost</programlistin
<para><emphasis>Stolen from the FAQ.</emphasis></para>
<para>The sendmail configuration that ships with FreeBSD is suited
for sites that connect directly to the Internet. Sites that wish
to exchange their mail via UUCP must install another <command>sendmail</command>
configuration file.</para>
<para>The sendmail configuration that ships with FreeBSD is suited for
sites that connect directly to the Internet. Sites that wish to
exchange their mail via UUCP must install another
<command>sendmail</command> configuration file.</para>
<para>Tweaking <filename>/etc/sendmail.cf</filename> manually is
considered something for purists. Sendmail version 8 comes with a
new approach of generating config files via some <command>m4</command> preprocessing, where the actual
hand-crafted configuration is on a higher abstraction level. You
should use the configuration files under
considered something for purists. Sendmail version 8 comes with a new
approach of generating config files via some <command>m4</command>
preprocessing, where the actual hand-crafted configuration is on a
higher abstraction level. You should use the configuration files under
<filename>/usr/src/usr.sbin/sendmail/cf</filename>.</para>
<para>If you did not install your system with full sources, the
<command>sendmail</command> config stuff has been broken out into a separate source
distribution tarball just for you. Assuming you have your CD-ROM
mounted, do:</para>
<command>sendmail</command> config stuff has been broken out into a
separate source distribution tarball just for you. Assuming you have
your CD-ROM mounted, do:</para>
<screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>tar -xvzf /cdrom/dists/src/ssmailcf.aa</userinput></screen>
<para>Do not panic, this is only a few hundred kilobytes in size.
The file <filename>README</filename> in the <filename>cf</filename> directory can serve as a basic
introduction to m4 configuration.</para>
<para>Do not panic, this is only a few hundred kilobytes in size. The
file <filename>README</filename> in the <filename>cf</filename>
directory can serve as a basic introduction to m4
configuration.</para>
<para>For UUCP delivery, you are best advised to use the
<emphasis>mailertable</emphasis> feature. This constitutes a
database that <command>sendmail</command> can use to base its routing decision
<emphasis>mailertable</emphasis> feature. This constitutes a database
that <command>sendmail</command> can use to base its routing decision
upon.</para>
<para>First, you have to create your <filename>.mc</filename> file.
The directory
<filename>/usr/src/usr.sbin/sendmail/cf/cf</filename> is the home
of these files. Look around, there are already a few examples.
Assuming you have named your file <filename>foo.mc</filename>, all
you need to do in order to convert it into a valid
<para>First, you have to create your <filename>.mc</filename> file. The
directory <filename>/usr/src/usr.sbin/sendmail/cf/cf</filename> is the
home of these files. Look around, there are already a few examples.
Assuming you have named your file <filename>foo.mc</filename>, all you
need to do in order to convert it into a valid
<filename>sendmail.cf</filename> is:</para>
<screen>&prompt.root; <userinput>cd /usr/src/usr.sbin/sendmail/cf/cf</userinput>
&prompt.root; <userinput>make foo.cf</userinput></screen>
<para>If you don't have a <filename>/usr/obj</filename> hiearchy,
then:</para>
<screen>&prompt.root; <userinput>cp foo.cf /etc/sendmail.cf</userinput></screen>
<para>Otherwise:</para>
<screen>&prompt.root; <userinput>cp /usr/obj/`pwd`/foo.cf /etc/sendmail.cf</userinput></screen>
<para>A typical <filename>.mc</filename> file might look
like:</para>
<para>A typical <filename>.mc</filename> file might look like:</para>
<programlisting>
include(`../m4/cf.m4')
@ -358,13 +333,12 @@ MAILER(uucp)
Cw <replaceable>your.alias.host.name</replaceable>
Cw <replaceable>youruucpnodename.UUCP</replaceable></programlisting>
<para>The <literal>nodns</literal> and
<literal>nocanonify</literal> features will prevent any usage of
the DNS during mail delivery. The <literal>UUCP_RELAY</literal>
clause is needed for bizarre reasons, do not ask. Simply put an
Internet hostname there that is able to handle .UUCP pseudo-domain
addresses; most likely, you will enter the mail relay of your ISP
there.</para>
<para>The <literal>nodns</literal> and <literal>nocanonify</literal>
features will prevent any usage of the DNS during mail delivery. The
<literal>UUCP_RELAY</literal> clause is needed for bizarre reasons, do
not ask. Simply put an Internet hostname there that is able to handle
.UUCP pseudo-domain addresses; most likely, you will enter the mail
relay of your ISP there.</para>
<para>Once you have this, you need this file called
<filename>/etc/mailertable</filename>. A typical example of this
@ -381,36 +355,35 @@ interface-business.de uucp-dom:if-bus
uucp-dom:horus if-bus.UUCP
uucp-dom:if-bus . uucp-dom:sax</programlisting>
<para>As you can see, this is part of a real-life file. The first
three lines handle special cases where domain-addressed mail
should not be sent out to the default route, but instead to some
UUCP neighbor in order to &ldquo;shortcut&rdquo; the delivery path. The
next line handles mail to the local Ethernet domain that can be
delivered using SMTP. Finally, the UUCP neighbors are mentioned
in the .UUCP pseudo-domain notation, to allow for a
<literal>uucp-neighbor!recipient</literal> override of the default rules. The
last line is always a single dot, matching everything else, with
UUCP delivery to a UUCP neighbor that serves as your universal
<para>As you can see, this is part of a real-life file. The first three
lines handle special cases where domain-addressed mail should not be
sent out to the default route, but instead to some UUCP neighbor in
order to &ldquo;shortcut&rdquo; the delivery path. The next line
handles mail to the local Ethernet domain that can be delivered using
SMTP. Finally, the UUCP neighbors are mentioned in the .UUCP
pseudo-domain notation, to allow for a
<literal>uucp-neighbor!recipient</literal> override of the default
rules. The last line is always a single dot, matching everything else,
with UUCP delivery to a UUCP neighbor that serves as your universal
mail gateway to the world. All of the node names behind the
<literal>uucp-dom:</literal> keyword must be valid UUCP
neighbors, as you can verify using the command <command>uuname</command>.</para>
<literal>uucp-dom:</literal> keyword must be valid UUCP neighbors, as
you can verify using the command <command>uuname</command>.</para>
<para>As a reminder that this file needs to be converted into a DBM
database file before being usable, the command line to accomplish
this is best placed as a comment at the top of the <filename>mailertable</filename>.
You always have to execute this command each time you change your
database file before being usable, the command line to accomplish this
is best placed as a comment at the top of the
<filename>mailertable</filename>. You always have to execute this
command each time you change your
<filename>mailertable</filename>.</para>
<para>Final hint: if you are uncertain whether some particular mail
routing would work, remember the <option>-bt</option> option to
<command>sendmail</command>. It starts <command>sendmail</command>
in &ldquo;address test
mode&rdquo;; simply enter <literal>0</literal>, followed by the address
you wish to test for the mail routing. The last line tells you
the used internal mail agent, the destination host this agent will
be called with, and the (possibly translated) address. Leave this
mode by typing Control-D.</para>
<command>sendmail</command>. It starts <command>sendmail</command> in
&ldquo;address test mode&rdquo;; simply enter <literal>0</literal>,
followed by the address you wish to test for the mail routing. The
last line tells you the used internal mail agent, the destination host
this agent will be called with, and the (possibly translated) address.
Leave this mode by typing Control-D.</para>
<screen>&prompt.user; <userinput>sendmail -bt</userinput>
ADDRESS TEST MODE (ruleset 3 NOT automatically invoked)
@ -419,8 +392,6 @@ Enter &lt;ruleset&gt; &lt;address&gt;
rewrite: ruleset 0 input: foo @ interface-business . de
&hellip;
rewrite: ruleset 0 returns: $# uucp-dom $@ if-bus $: foo &lt; @ interface-business . de</screen>
</sect2>
</sect1>
@ -429,30 +400,31 @@ rewrite: ruleset 0 returns: $# uucp-dom $@ if-bus $: foo &lt; @ interface-busin
<para><emphasis>Migration from FAQ.</emphasis></para>
<sect2>
<title>Why do I have to use the FQDN for hosts on my site?</title>
<para>You will probably find that the host is actually in a
different domain; for example, if you are in <hostid role="fqdn">foo.bar.edu</hostid> and you
wish to reach a host called <hostid>mumble</hostid> in the <hostid
role="domainname">bar.edu</hostid> domain, you
will have to refer to it by the fully-qualified domain name,
<hostid role="fqdn">mumble.bar.edu</hostid>, instead of just <hostid>mumble</hostid>.</para>
<para>You will probably find that the host is actually in a different
domain; for example, if you are in <hostid
role="fqdn">foo.bar.edu</hostid> and you wish to reach a host called
<hostid>mumble</hostid> in the <hostid
role="domainname">bar.edu</hostid> domain, you will have to refer to
it by the fully-qualified domain name, <hostid
role="fqdn">mumble.bar.edu</hostid>, instead of just
<hostid>mumble</hostid>.</para>
<para>Traditionally, this was allowed by BSD BIND resolvers. However
the current version of <application>BIND</application> that ships with
<para>Traditionally, this was allowed by BSD BIND resolvers. However the
current version of <application>BIND</application> that ships with
FreeBSD no longer provides default abbreviations for non-fully
qualified domain names other than the domain you are in. So an
unqualified host <hostid>mumble</hostid> must either
be found as <hostid role="fqdn">mumble.foo.bar.edu</hostid>, or
it will be searched for in the root domain.</para>
unqualified host <hostid>mumble</hostid> must either be found as
<hostid role="fqdn">mumble.foo.bar.edu</hostid>, or it will be
searched for in the root domain.</para>
<para>This is different from the previous behavior, where the search
continued across <hostid role="domainname">mumble.bar.edu</hostid>,
and <hostid role="domainname">mumble.edu</hostid>. Have a look at
RFC 1535 for why this was considered bad practice, or even a
security hole.</para>
and <hostid role="domainname">mumble.edu</hostid>. Have a look at RFC
1535 for why this was considered bad practice, or even a security
hole.</para>
<para>As a good workaround, you can place the line
@ -464,15 +436,14 @@ search foo.bar.edu bar.edu</programlisting>
<programlisting>
domain foo.bar.edu</programlisting>
into your <filename>/etc/resolv.conf</filename>. However,
make sure that the search order does not go beyond the &ldquo;boundary
between local and public administration&rdquo;, as RFC 1535 calls
it.</para>
into your <filename>/etc/resolv.conf</filename>. However, make sure
that the search order does not go beyond the &ldquo;boundary between
local and public administration&rdquo;, as RFC 1535 calls it.</para>
</sect2>
<sect2>
<title>Sendmail says <errorname>mail loops back to myself</errorname></title>
<title>Sendmail says <errorname>mail loops back to
myself</errorname></title>
<para>This is answered in the sendmail FAQ as follows:</para>
@ -495,41 +466,41 @@ to /etc/sendmail.cf.</programlisting>
<filename>/usr/src/usr.sbin/sendmail</filename> and is recommended
reading if you want to do any &ldquo;tweaking&rdquo; of your mail
setup.</para>
</sect2>
<sect2>
<title>How can I do E-Mail with a dialup PPP host?</title>
<para>You want to connect a FreeBSD box on a lan, to the Internet.
The FreeBSD box will be a mail gateway for the lan. The PPP
connection is non-dedicated.</para>
<para>You want to connect a FreeBSD box on a lan, to the Internet. The
FreeBSD box will be a mail gateway for the lan. The PPP connection is
non-dedicated.</para>
<para>There are at least two way to do this.</para>
<para>The other is to use UUCP.</para>
<para>The key is to get a Internet site to provide secondary MX
services for your domain. For example:</para>
<para>The key is to get a Internet site to provide secondary MX services
for your domain. For example:</para>
<programlisting>
bigco.com. MX 10 bigco.com.
MX 20 smalliap.com.</programlisting>
<para>Only one host should be specified as the final recipient ( add
<literal>Cw bigco.com</literal> in <filename>/etc/sendmail.cf</filename> on
bigco.com).</para>
<literal>Cw bigco.com</literal> in
<filename>/etc/sendmail.cf</filename> on bigco.com).</para>
<para>When the senders <command>sendmail</command> is trying to deliver the mail it
will try to connect to you over the modem link. It will most
likely time out because you are not online. <command>sendmail</command> will
automatically deliver it to the secondary MX site, ie your
Internet provider. The secondary MX site will try every
(<literal>sendmail_flags = "-bd -q15m"</literal> in
<filename>/etc/rc.conf</filename> ) 15 minutes to connect to your
host to deliver the mail to the primary MX site.</para>
<para>When the senders <command>sendmail</command> is trying to deliver
the mail it will try to connect to you over the modem link. It will
most likely time out because you are not online.
<command>sendmail</command> will automatically deliver it to the
secondary MX site, ie your Internet provider. The secondary MX site
will try every (<literal>sendmail_flags = "-bd -q15m"</literal> in
<filename>/etc/rc.conf</filename> ) 15 minutes to connect to your host
to deliver the mail to the primary MX site.</para>
<para>You might want to use something like this as a login script.</para>
<para>You might want to use something like this as a login
script.</para>
<programlisting>
#!/bin/sh
@ -537,11 +508,10 @@ bigco.com. MX 10 bigco.com.
( sleep 60 ; /usr/sbin/sendmail -q ) &amp;
/usr/sbin/ppp -direct pppbigco</programlisting>
<para>If you are going to create a separate
login script for a user you could use <command>sendmail
-qRbigco.com</command> instead in the script above. This will
force all mail in your queue for bigco.com to be processed
immediately.</para>
<para>If you are going to create a separate login script for a user you
could use <command>sendmail -qRbigco.com</command> instead in the
script above. This will force all mail in your queue for bigco.com to
be processed immediately.</para>
<para>A further refinement of the situation is as follows.</para>
@ -574,11 +544,9 @@ the customer connection. You then send to your customer. Only works for
"hosts", so you need to get your customer to name their mail machine
"customer.com" as well as "hostname.customer.com" in the DNS. Just put
an A record in the DNS for "customer.com".</programlisting>
</sect2>
</sect1>
</chapter>
</chapter>
<!--
Local Variables:

636
en/handbook/mirrors/chapter.sgml
View file

File diff suppressed because it is too large Load diff

18
en/handbook/pgpkeys/chapter.sgml
View file

@ -1,17 +1,16 @@
<chapter id="pgpkeys">
<chapter id="pgpkeys">
<title>PGP keys</title>
<para>In case you need to verify a signature or send encrypted email to
one of the officers or core team members a number of keys are
provided here for your convenience.</para>
<para>In case you need to verify a signature or send encrypted email to one
of the officers or core team members a number of keys are provided here
for your convenience.</para>
<sect1>
<title>Officers</title>
<sect2>
<title>FreeBSD Security Officer <email>security-officer@freebsd.org</email></title>
<title>FreeBSD Security Officer
<email>security-officer@freebsd.org</email></title>
<programlisting>
FreeBSD Security Officer &lt;security-officer@freebsd.org&gt;
@ -43,7 +42,6 @@ v4Xhp6a8RtDdUMBOTtro16iulGiRrCKxzVgEl4i+9Z0ZiE6BWlg5AetoF5n3mGk1
lw==
=ipyA
-----END PGP PUBLIC KEY BLOCK-----</programlisting>
</sect2>
<sect2>
@ -74,14 +72,12 @@ RzUrblyF84tJyA7Rr1p+A7dxf7je3Zx5QMEXosWL1WGnS5vC9YH2WZwv6sCU61gU
rSy9z8KHlBEHh+Z6fdRMrjd9byPf+n3cktT0NhS23oXB1ZhNZcB2KKhVPlNctMqO
3gTYx+Nlo6xqjR+J2NnBYU8p =7fQV
-----END PGP PUBLIC KEY BLOCK-----</programlisting>
</sect2>
</sect1>
<sect1>
<title>Core Team members</title>
<sect2>
<title>&a.asami;</title>
@ -564,7 +560,7 @@ xDZaEUQEbWqxfiwuzizAjkaxrW7dBbWILwWqrYF5TXClw+oUU/oIUW4t6t+GpAO1
-----END PGP PUBLIC KEY BLOCK-----</programlisting>
</sect2>
</sect1>
</chapter>
</chapter>
<!--
Local Variables:

271
en/handbook/policies/chapter.sgml
View file

@ -1,11 +1,10 @@
<chapter id="policies">
<chapter id="policies">
<title>Source Tree Guidelines and Policies</title>
<para><emphasis>Contributed by &a.phk;.</emphasis></para>
<para>This chapter documents various guidelines and policies in force
for the FreeBSD source tree.</para>
<para>This chapter documents various guidelines and policies in force for
the FreeBSD source tree.</para>
<sect1 id="policies-maintainer">
<title><makevar>MAINTAINER</makevar> on Makefiles</title>
@ -13,36 +12,33 @@
<para>June 1996.</para>
<para>If a particular portion of the FreeBSD distribution is being
maintained by a person or group of persons, they can communicate
this fact to the world by adding a
maintained by a person or group of persons, they can communicate this
fact to the world by adding a
<programlisting>
MAINTAINER= email-addresses</programlisting>
line to the <filename>Makefile</filename>s covering this portion
of the source tree.</para>
line to the <filename>Makefile</filename>s covering this portion of the
source tree.</para>
<para>The semantics of this are as follows:</para>
<para>The maintainer owns and is responsible for that code. This
means that he is responsible for fixing bugs and answer problem
reports pertaining to that piece of the code, and in the case of
contributed software, for tracking new versions, as
appropriate.</para>
<para>The maintainer owns and is responsible for that code. This means
that he is responsible for fixing bugs and answer problem reports
pertaining to that piece of the code, and in the case of contributed
software, for tracking new versions, as appropriate.</para>
<para>Changes to directories which have a maintainer defined shall be
sent to the maintainer for review before being committed. Only if
the maintainer does not respond for an unacceptable period of time,
to several emails, will it be acceptable to commit changes without
review by the maintainer. However, it is suggested that you try and
have the changes reviewed by someone else if at all
possible.</para>
<para>Changes to directories which have a maintainer defined shall be sent
to the maintainer for review before being committed. Only if the
maintainer does not respond for an unacceptable period of time, to
several emails, will it be acceptable to commit changes without review
by the maintainer. However, it is suggested that you try and have the
changes reviewed by someone else if at all possible.</para>
<para>It is of course not acceptable to add a person or group as
maintainer unless they agree to assume this duty. On the other hand
it doesn't have to be a committer and it can easily be a group of
maintainer unless they agree to assume this duty. On the other hand it
doesn't have to be a committer and it can easily be a group of
people.</para>
</sect1>
<sect1>
@ -52,31 +48,31 @@ MAINTAINER= email-addresses</programlisting>
<para>June 1996.</para>
<para>Some parts of the FreeBSD distribution consist of software that
is actively being maintained outside the FreeBSD project. For
historical reasons, we call this <emphasis>contributed</emphasis>
software. Some examples are perl, gcc and patch.</para>
<para>Some parts of the FreeBSD distribution consist of software that is
actively being maintained outside the FreeBSD project. For historical
reasons, we call this <emphasis>contributed</emphasis> software. Some
examples are perl, gcc and patch.</para>
<para>Over the last couple of years, various methods have been used in
dealing with this type of software and all have some number of
advantages and drawbacks. No clear winner has emerged.</para>
<para>Since this is the case, after some debate one of these methods
has been selected as the &ldquo;official&rdquo; method and will be required for
future imports of software of this kind. Furthermore, it is
strongly suggested that existing contributed software converge on
this model over time, as it has significant advantages over the old
method, including the ability to easily obtain diffs relative to the
&ldquo;official&rdquo; versions of the source by everyone (even without cvs
access). This will make it significantly easier to return changes
<para>Since this is the case, after some debate one of these methods has
been selected as the &ldquo;official&rdquo; method and will be required
for future imports of software of this kind. Furthermore, it is
strongly suggested that existing contributed software converge on this
model over time, as it has significant advantages over the old method,
including the ability to easily obtain diffs relative to the
&ldquo;official&rdquo; versions of the source by everyone (even without
cvs access). This will make it significantly easier to return changes
to the primary developers of the contributed software.</para>
<para>Ultimately, however, it comes down to the people actually doing
the work. If using this model is particularly unsuited to the
package being dealt with, exceptions to these rules may be granted
only with the approval of the core team and with the general
consensus of the other developers. The ability to maintain the
package in the future will be a key issue in the decisions.</para>
<para>Ultimately, however, it comes down to the people actually doing the
work. If using this model is particularly unsuited to the package being
dealt with, exceptions to these rules may be granted only with the
approval of the core team and with the general consensus of the other
developers. The ability to maintain the package in the future will be a
key issue in the decisions.</para>
<note>
<para>Because of some unfortunate design limitations with the RCS file
@ -93,76 +89,72 @@ MAINTAINER= email-addresses</programlisting>
language will be used as example of how this model works:</para>
<para><filename>src/contrib/tcl</filename> contains the source as
distributed by the maintainers of this package. Parts that are
entirely not applicable for FreeBSD can be removed. In the case of
Tcl, the <filename>mac</filename>, <filename>win</filename> and
<filename>compat</filename> subdirectories were eliminated before
the import</para>
distributed by the maintainers of this package. Parts that are entirely
not applicable for FreeBSD can be removed. In the case of Tcl, the
<filename>mac</filename>, <filename>win</filename> and
<filename>compat</filename> subdirectories were eliminated before the
import</para>
<para><filename>src/lib/libtcl</filename> contains only a "bmake style"
<filename>Makefile</filename> that uses the standard
<filename>bsd.lib.mk</filename> makefile rules to produce the
library and install the documentation.</para>
<filename>bsd.lib.mk</filename> makefile rules to produce the library
and install the documentation.</para>
<para><filename>src/usr.bin/tclsh</filename> contains only a bmake style
<filename>Makefile</filename> which will produce and install the
<command>tclsh</command> program and its associated man-pages using the standard
<filename>bsd.prog.mk</filename> rules.</para>
<command>tclsh</command> program and its associated man-pages using the
standard <filename>bsd.prog.mk</filename> rules.</para>
<para><filename>src/tools/tools/tcl_bmake</filename> contains a couple of
shell-scripts that can be of help when the tcl software needs
updating. These are not part of the built or installed
software.</para>
shell-scripts that can be of help when the tcl software needs updating.
These are not part of the built or installed software.</para>
<para>The important thing here is that the
<filename>src/contrib/tcl</filename> directory is created according
to the rules: It is supposed to contain the sources as distributed
(on a proper CVS vendor-branch and without RCS keyword expansion) with as few FreeBSD-specific changes
as possible. The 'easy-import' tool on freefall will assist in
doing the import, but if there are any doubts on how to go about it,
it is imperative that you ask first and not blunder ahead and hope
it &ldquo;works out&rdquo;. CVS is not forgiving of import accidents and a fair
amount of effort is required to back out major mistakes.</para>
<filename>src/contrib/tcl</filename> directory is created according to
the rules: It is supposed to contain the sources as distributed (on a
proper CVS vendor-branch and without RCS keyword expansion) with as few
FreeBSD-specific changes as possible. The 'easy-import' tool on
freefall will assist in doing the import, but if there are any doubts on
how to go about it, it is imperative that you ask first and not blunder
ahead and hope it &ldquo;works out&rdquo;. CVS is not forgiving of
import accidents and a fair amount of effort is required to back out
major mistakes.</para>
<para>Because of the previously mentioned design limitations with CVS's vendor
branches, it is required that &ldquo;official&rdquo; patches from the vendor be
applied to the original distributed sources and the result
re-imported onto the vendor branch again. Official patches should
never be patched into the FreeBSD checked out version and
"committed", as this destroys the vendor branch coherency and makes
importing future versions rather difficult as there will be
conflicts.</para>
<para>Because of the previously mentioned design limitations with CVS's
vendor branches, it is required that &ldquo;official&rdquo; patches from
the vendor be applied to the original distributed sources and the result
re-imported onto the vendor branch again. Official patches should never
be patched into the FreeBSD checked out version and "committed", as this
destroys the vendor branch coherency and makes importing future versions
rather difficult as there will be conflicts.</para>
<para>Since many packages contain files that are meant for
compatibility with other architectures and environments that
FreeBSD, it is permissible to remove parts of the distribution tree
that are of no interest to FreeBSD in order to save space. Files
containing copyright notices and release-note kind of information
applicable to the remaining files shall <emphasis>not</emphasis> be
removed.</para>
<para>Since many packages contain files that are meant for compatibility
with other architectures and environments that FreeBSD, it is
permissible to remove parts of the distribution tree that are of no
interest to FreeBSD in order to save space. Files containing copyright
notices and release-note kind of information applicable to the remaining
files shall <emphasis>not</emphasis> be removed.</para>
<para>If it seems easier, the <command>bmake</command> <filename>Makefile</filename>s
can be produced from the dist tree automatically by some utility,
something which would hopefully make it even easier to upgrade to a
new version. If this is done, be sure to check in such utilities
(as necessary) in the <filename>src/tools</filename> directory along
with the port itself so that it is available to future
maintainers.</para>
<para>In the <filename>src/contrib/tcl</filename> level directory, a
file called <filename>FREEBSD-upgrade</filename> should be added and
it should states things like:</para>
<para>If it seems easier, the <command>bmake</command>
<filename>Makefile</filename>s can be produced from the dist tree
automatically by some utility, something which would hopefully make it
even easier to upgrade to a new version. If this is done, be sure to
check in such utilities (as necessary) in the
<filename>src/tools</filename> directory along with the port itself so
that it is available to future maintainers.</para>
<para>In the <filename>src/contrib/tcl</filename> level directory, a file
called <filename>FREEBSD-upgrade</filename> should be added and it
should states things like:</para>
<itemizedlist>
<listitem>
<para>Which files have been left out</para>
</listitem>
<listitem>
<para>Where the original distribution was obtained from and/or
the official master site.</para>
<para>Where the original distribution was obtained from and/or the
official master site.</para>
</listitem>
<listitem>
@ -170,18 +162,15 @@ MAINTAINER= email-addresses</programlisting>
</listitem>
<listitem>
<para>Perhaps an overview of the FreeBSD-specific changes that
have been made.</para>
<para>Perhaps an overview of the FreeBSD-specific changes that have
been made.</para>
</listitem>
</itemizedlist>
<para>However, please do not import
<filename>FREEBSD-upgrade</filename> with the contributed source.
Rather you should <command>cvs add FREEBSD-upgrade ; cvs ci</command> after the
initial import. Example wording from
<filename>src/contrib/cpio</filename> is below:</para>
<para>However, please do not import <filename>FREEBSD-upgrade</filename>
with the contributed source. Rather you should <command>cvs add
FREEBSD-upgrade ; cvs ci</command> after the initial import. Example
wording from <filename>src/contrib/cpio</filename> is below:</para>
<programlisting>
This directory contains virgin sources of the original distribution files
@ -222,78 +211,74 @@ All local changes should be submitted to "cpio@gnu.ai.mit.edu" for
inclusion in the next vendor release.
obrien@freebsd.org - 30 March 1997</programlisting>
</sect1>
<sect1 id="policies-shlib">
<title>Shared Libraries</title>
<para><emphasis>Contributed by &a.asami;, &a.peter;, and
&a.obrien;.<!-- <br> --> 9 December 1996.</emphasis></para>
<para><emphasis>Contributed by &a.asami;, &a.peter;, and &a.obrien;.<!--
<br> --> 9 December 1996.</emphasis></para>
<para>If you are adding shared library support to a port or other
piece of software that doesn't have one, the version numbers should
follow these rules. Generally, the resulting numbers will have
nothing to do with the release version of the software.</para>
<para>If you are adding shared library support to a port or other piece of
software that doesn't have one, the version numbers should follow these
rules. Generally, the resulting numbers will have nothing to do with
the release version of the software.</para>
<para>The three principles of shared library building are:</para>
<itemizedlist>
<listitem>
<para>Start from <literal>1.0</literal></para>
</listitem>
<listitem>
<para>If there is a change that is backwards compatible, bump
minor number</para>
</listitem>
<listitem>
<para>If there is an incompatible change, bump major
<para>If there is a change that is backwards compatible, bump minor
number</para>
</listitem>
<listitem>
<para>If there is an incompatible change, bump major number</para>
</listitem>
</itemizedlist>
<para>For instance, added functions and bugfixes result in the minor
version number being bumped, while deleted functions, changed
function call syntax etc. will force the major version number to
change.</para>
version number being bumped, while deleted functions, changed function
call syntax etc. will force the major version number to change.</para>
<para>Stick to version numbers of the form major.minor (<replaceable>x</replaceable>.<replaceable>y</replaceable>). Our
dynamic linker does not handle version numbers of the form <replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable>
well. Any version number after the <replaceable>y</replaceable> (ie. the third digit) is
totally ignored when comparing shared lib version numbers to decide
which library to link with. Given two shared libraries that differ
only in the &ldquo;micro&rdquo; revision, <command>ld.so</command> will link with the higher one.
Ie: if you link with <filename>libfoo.so.3.3.3</filename>, the
linker only records <literal>3.3</literal> in the headers, and will link with anything
starting with <replaceable>libfoo.so.3</replaceable>.<replaceable>(anything &gt;=
3)</replaceable>.<replaceable>(highest available)</replaceable>.</para>
<para>Stick to version numbers of the form major.minor
(<replaceable>x</replaceable>.<replaceable>y</replaceable>). Our
dynamic linker does not handle version numbers of the form
<replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable>
well. Any version number after the <replaceable>y</replaceable>
(ie. the third digit) is totally ignored when comparing shared lib
version numbers to decide which library to link with. Given two shared
libraries that differ only in the &ldquo;micro&rdquo; revision,
<command>ld.so</command> will link with the higher one. Ie: if you link
with <filename>libfoo.so.3.3.3</filename>, the linker only records
<literal>3.3</literal> in the headers, and will link with anything
starting with
<replaceable>libfoo.so.3</replaceable>.<replaceable>(anything &gt;=
3)</replaceable>.<replaceable>(highest
available)</replaceable>.</para>
<note>
<para><command>ld.so</command> will always use the highest
&ldquo;minor&rdquo; revision. Ie: it will use <filename>libc.so.2.2</filename>
in preference to <filename>libc.so.2.0</filename>, even if the
program was initially linked with
<filename>libc.so.2.0</filename>.</para>
&ldquo;minor&rdquo; revision. Ie: it will use
<filename>libc.so.2.2</filename> in preference to
<filename>libc.so.2.0</filename>, even if the program was initially
linked with <filename>libc.so.2.0</filename>.</para>
</note>
<para>For non-port libraries, it is also our policy to change the
shared library version number only once between releases. When you
make a change to a system library that requires the version number
to be bumped, check the <filename>Makefile</filename>'s commit logs.
It is the responsibility of the committer to ensure that the first
such change since the release will result in the shared library
version number in the <filename>Makefile</filename> to be updated,
and any subsequent changes will not.</para>
<para>For non-port libraries, it is also our policy to change the shared
library version number only once between releases. When you make a
change to a system library that requires the version number to be
bumped, check the <filename>Makefile</filename>'s commit logs. It is the
responsibility of the committer to ensure that the first such change
since the release will result in the shared library version number in
the <filename>Makefile</filename> to be updated, and any subsequent
changes will not.</para>
</sect1>
</chapter>
</chapter>
<!--
Local Variables:

3195
en/handbook/ports/chapter.sgml
View file

File diff suppressed because it is too large Load diff

1700
en/handbook/ppp-and-slip/chapter.sgml
View file

File diff suppressed because it is too large Load diff

4150
en/handbook/printing/chapter.sgml
View file

File diff suppressed because it is too large Load diff

242
en/handbook/quotas/chapter.sgml
View file

@ -1,38 +1,35 @@
<chapter id="quotas">
<chapter id="quotas">
<title>Disk Quotas</title>
<para><emphasis>Contributed by &a.mpp;.<!-- <br> -->26 February
1996</emphasis></para>
<para>Quotas are an optional feature of the operating system that allow
you to limit the amount of disk space and/or the number of files a
user, or members of a group, may allocate on a per-file system basis.
This is used most often on timesharing systems where it is desirable
to limit the amount of resources any one user or group of users may
allocate. This will prevent one user from consuming all of the
available disk space.</para>
<para>Quotas are an optional feature of the operating system that allow you
to limit the amount of disk space and/or the number of files a user, or
members of a group, may allocate on a per-file system basis. This is used
most often on timesharing systems where it is desirable to limit the
amount of resources any one user or group of users may allocate. This
will prevent one user from consuming all of the available disk
space.</para>
<sect1>
<title>Configuring Your System to Enable Disk Quotas</title>
<para>Before attempting to use disk quotas it is necessary to make
sure that quotas are configured in your kernel. This is done by
adding the following line to your kernel configuration file:</para>
<para>Before attempting to use disk quotas it is necessary to make sure
that quotas are configured in your kernel. This is done by adding the
following line to your kernel configuration file:</para>
<programlisting>
options QUOTA</programlisting>
<para>The
stock <filename>GENERIC</filename> kernel does not have this enabled
by default, so you will have to configure, build and install a
custom kernel in order to use disk quotas. Please refer to the
<link linkend="kernelconfig">Configuring the FreeBSD Kernel</link>
section for more information on kernel configuration.</para>
<para>The stock <filename>GENERIC</filename> kernel does not have this
enabled by default, so you will have to configure, build and install a
custom kernel in order to use disk quotas. Please refer to the <link
linkend="kernelconfig">Configuring the FreeBSD Kernel</link> section
for more information on kernel configuration.</para>
<para>Next you will need to enable disk quotas in
<filename>/etc/sysconfig</filename>. This is done by changing the
line:
<filename>/etc/sysconfig</filename>. This is done by changing the line:
<programlisting>
quotas=NO</programlisting>
@ -42,105 +39,98 @@ quotas=NO</programlisting>
<programlisting>
quotas=YES</programlisting></para>
<para>If you are running FreeBSD 2.2.2 or later, the configuration
file will be <filename>/etc/rc.conf</filename> instead and the
variable name changed to:</para>
<para>If you are running FreeBSD 2.2.2 or later, the configuration file
will be <filename>/etc/rc.conf</filename> instead and the variable name
changed to:</para>
<programlisting>
check_quotas=YES</programlisting>
<para>Finally you will need to edit <filename>/etc/fstab</filename> to
enable disk quotas on a per-file system basis. This is where you
can either enable user or group quotas or both for all of your file
enable disk quotas on a per-file system basis. This is where you can
either enable user or group quotas or both for all of your file
systems.</para>
<para>To enable per-user quotas on a file system, add the <literal>userquota</literal> option to the options field in the
<filename>/etc/fstab</filename> entry for the file system you want
to to enable quotas on. For example:</para>
<para>To enable per-user quotas on a file system, add the
<literal>userquota</literal> option to the options field in the
<filename>/etc/fstab</filename> entry for the file system you want to to
enable quotas on. For example:</para>
<programlisting>
/dev/sd1s2g /home ufs rw,userquota 1 2</programlisting>
<para>Similarly, to enable group quotas, use the
<literal>groupquota</literal> option instead of the <literal>userquota</literal> keyword. To enable both user and
group quotas, change the entry as follows:</para>
<literal>groupquota</literal> option instead of the
<literal>userquota</literal> keyword. To enable both user and group
quotas, change the entry as follows:</para>
<programlisting>
/dev/sd1s2g /home ufs rw,userquota,groupquota 1 2</programlisting>
<para>By default the quota files are stored in the root directory of
the file system with the names <filename>quota.user</filename> and
<filename>quota.group</filename> for user and group quotas
respectively. See <command>man fstab</command> for more
information. Even though that man page says that you can specify an
alternate location for the quota files, this is not recommended
since all of the various quota utilities do not seem to handle this
properly.</para>
<para>By default the quota files are stored in the root directory of the
file system with the names <filename>quota.user</filename> and
<filename>quota.group</filename> for user and group quotas respectively.
See <command>man fstab</command> for more information. Even though that
man page says that you can specify an alternate location for the quota
files, this is not recommended since all of the various quota utilities
do not seem to handle this properly.</para>
<para>At this point you should reboot your system with your new
kernel. <filename>/etc/rc</filename> will automatically run the
appropriate commands to create the initial quota files for all of
the quotas you enabled in <filename>/etc/fstab</filename>, so there
is no need to manually create any zero length quota files.</para>
<para>In the normal course of operations you should not be required to
run the <command>quotacheck</command>, <command>quotaon</command>, or <command>quotaoff</command> commands manually. However, you may
want to read their man pages just to be familiar with their
operation.</para>
<para>At this point you should reboot your system with your new kernel.
<filename>/etc/rc</filename> will automatically run the appropriate
commands to create the initial quota files for all of the quotas you
enabled in <filename>/etc/fstab</filename>, so there is no need to
manually create any zero length quota files.</para>
<para>In the normal course of operations you should not be required to run
the <command>quotacheck</command>, <command>quotaon</command>, or
<command>quotaoff</command> commands manually. However, you may want to
read their man pages just to be familiar with their operation.</para>
</sect1>
<sect1>
<title>Setting Quota Limits</title>
<para>Once you have configured your system to enable quotas, verify
that they really are enabled. An easy way to do this is to run</para>
<para>Once you have configured your system to enable quotas, verify that
they really are enabled. An easy way to do this is to run</para>
<screen>&prompt.root; <userinput>quota -v</userinput></screen>
<para>You should see a one line summary of
disk usage and current quota limits for each file system that quotas
are enabled on.</para>
<para>You should see a one line summary of disk usage and current quota
limits for each file system that quotas are enabled on.</para>
<para>You are now ready to start assigning quota limits with the
<command>edquota</command> command.</para>
<para>You have several options on how to enforce limits on the amount
of disk space a user or group may allocate, and how many files they
may create. You may limit allocations based on disk space (block
quotas) or number of files (inode quotas) or a combination of both.
Each of these limits are further broken down into two categories:
hard and soft limits.</para>
<para>You have several options on how to enforce limits on the amount of
disk space a user or group may allocate, and how many files they may
create. You may limit allocations based on disk space (block quotas) or
number of files (inode quotas) or a combination of both. Each of these
limits are further broken down into two categories: hard and soft
limits.</para>
<para>A hard limit may not be exceeded. Once a user reaches their
hard limit they may not make any further allocations on the file
system in question. For example, if the user has a hard limit of
500 blocks on a file system and is currently using 490 blocks, the
user can only allocate an additional 10 blocks. Attempting to
allocate an additional 11 blocks will fail.</para>
<para>A hard limit may not be exceeded. Once a user reaches their hard
limit they may not make any further allocations on the file system in
question. For example, if the user has a hard limit of 500 blocks on a
file system and is currently using 490 blocks, the user can only
allocate an additional 10 blocks. Attempting to allocate an additional
11 blocks will fail.</para>
<para>Soft limits on the other hand can be exceeded for a limited
amount of time. This period of time is known as the grace period,
which is one week by default. If a user stays over his or her soft
limit longer than their grace period, the soft limit will turn into
a hard limit and no further allocations will be allowed. When the
user drops back below the soft limit, the grace period will be
reset.</para>
<para>Soft limits on the other hand can be exceeded for a limited amount
of time. This period of time is known as the grace period, which is one
week by default. If a user stays over his or her soft limit longer than
their grace period, the soft limit will turn into a hard limit and no
further allocations will be allowed. When the user drops back below the
soft limit, the grace period will be reset.</para>
<para>The following is an example of what you might see when you run
then <command>edquota</command> command. When the
<command>edquota</command> command is invoked, you are
placed into the editor specified by the <envar>EDITOR</envar>
environment variable, or in the <command>vi</command>
editor if the <envar>EDITOR</envar> variable is not set, to
allow you to edit the quota limits.</para>
<command>edquota</command> command is invoked, you are placed into the
editor specified by the <envar>EDITOR</envar> environment variable, or
in the <command>vi</command> editor if the <envar>EDITOR</envar>
variable is not set, to allow you to edit the quota limits.</para>
<screen>&prompt.root; <userinput>edquota -u test</userinput></screen>
<programlisting>
Quotas for user test:
/usr: blocks in use: 65, limits (soft = 50, hard = 75)
@ -148,57 +138,48 @@ Quotas for user test:
/usr/var: blocks in use: 0, limits (soft = 50, hard = 75)
inodes in use: 0, limits (soft = 50, hard = 60)</programlisting>
<para>You will
normally see two lines for each file system that has quotas enabled.
One line for the block limits, and one line for inode limits.
Simply change the value you want updated to modify the quota limit.
For example, to raise this users block limit from a soft limit of 50
and a hard limit of 75 to a soft limit of 500 and a hard limit of
600, change:
<para>You will normally see two lines for each file system that has quotas
enabled. One line for the block limits, and one line for inode limits.
Simply change the value you want updated to modify the quota limit. For
example, to raise this users block limit from a soft limit of 50 and a
hard limit of 75 to a soft limit of 500 and a hard limit of 600, change:
<programlisting> /usr: blocks in use: 65, limits (soft = 50, hard =
75)</programlisting> to: <programlisting> /usr: blocks in use: 65,
limits (soft = 500, hard = 600)</programlisting></para>
<programlisting>
/usr: blocks in use: 65, limits (soft = 50, hard = 75)</programlisting> to:
<programlisting>
/usr: blocks in use: 65, limits (soft = 500, hard = 600)</programlisting></para>
<para>The new
quota limits will be in place when you exit the editor.</para>
<para>Sometimes it is desirable to set quota limits on a range of
uids. This can be done by use of the <option>-p</option> option on
the <command>edquota</command> command. First, assign
the desired quota limit to a user, and then run <command>edquota -p
protouser startuid-enduid</command>. For example, if user
<username>test</username> has the desired quota limits, the
following command can be used to duplicate those quota limits for
uids 10,000 through 19,999:</para>
<para>The new quota limits will be in place when you exit the
editor.</para>
<para>Sometimes it is desirable to set quota limits on a range of uids.
This can be done by use of the <option>-p</option> option on the
<command>edquota</command> command. First, assign the desired quota
limit to a user, and then run <command>edquota -p protouser
startuid-enduid</command>. For example, if user
<username>test</username> has the desired quota limits, the following
command can be used to duplicate those quota limits for uids 10,000
through 19,999:</para>
<screen>&prompt.root; <userinput>edquota -p test 10000-19999</userinput></screen>
<para>The ability to specify uid ranges was added to the system after
2.1 was released. If you need this feature on a 2.1 system, you
will need to obtain a newer copy of edquota.</para>
<para>The ability to specify uid ranges was added to the system after 2.1
was released. If you need this feature on a 2.1 system, you will need
to obtain a newer copy of edquota.</para>
<para>See <command>man edquota</command> for more detailed
information.</para>
</sect1>
<sect1>
<title>Checking Quota Limits and Disk Usage</title>
<para>You can use either the <command>quota</command> or
the <command>repquota</command> commands to check quota
limits and disk usage. The <command>quota</command>
command can be used to check individual user and group quotas and
disk usage. Only the super-user may examine quotas and usage for
other users, or for groups that they are not a member of. The
<command>repquota</command> command can be used to get a
summary of all quotas and disk usage for file systems with quotas
enabled.</para>
<para>You can use either the <command>quota</command> or the
<command>repquota</command> commands to check quota limits and disk
usage. The <command>quota</command> command can be used to check
individual user and group quotas and disk usage. Only the super-user
may examine quotas and usage for other users, or for groups that they
are not a member of. The <command>repquota</command> command can be
used to get a summary of all quotas and disk usage for file systems with
quotas enabled.</para>
<para>The following is some sample output from the <command>quota
-v</command> command for a user that has quota limits on two file
@ -211,27 +192,26 @@ Disk quotas for user test (uid 1002):
/usr 65* 50 75 5days 7 50 60
/usr/var 0 50 75 0 50 60</programlisting>
<para>On the <filename>/usr</filename> file system in the above example this
user is currently 15 blocks over their soft limit of 50 blocks and
has 5 days of their grace period left. Note the asterisk <literal>*</literal> which
indicates that the user is currently over their quota limit.</para>
<para>On the <filename>/usr</filename> file system in the above example
this user is currently 15 blocks over their soft limit of 50 blocks and
has 5 days of their grace period left. Note the asterisk
<literal>*</literal> which indicates that the user is currently over
their quota limit.</para>
<para>Normally file systems that the user is not using any disk space
on will not show up in the output from the <command>quota</command> command, even if they have a quota limit
assigned for that file system. The <option>-v</option> option will
display those file systems, such as the
<filename>/usr/var</filename> file system in the above
<para>Normally file systems that the user is not using any disk space on
will not show up in the output from the <command>quota</command>
command, even if they have a quota limit assigned for that file system.
The <option>-v</option> option will display those file systems, such as
the <filename>/usr/var</filename> file system in the above
example.</para>
</sect1>
<sect1>
<title>* Quotas over NFS</title>
<para>This section is still under development.</para>
</sect1>
</chapter>
</chapter>
<!--
Local Variables:

1468
en/handbook/security/chapter.sgml
View file

File diff suppressed because it is too large Load diff

1788
en/handbook/serialcomms/chapter.sgml
View file

File diff suppressed because it is too large Load diff

173
en/handbook/staff/chapter.sgml
View file

@ -1,9 +1,8 @@
<chapter id="staff">
<chapter id="staff">
<title>FreeBSD Project Staff</title>
<para>The FreeBSD Project is managed and operated by the following
groups of people:</para>
<para>The FreeBSD Project is managed and operated by the following groups of
people:</para>
<sect1 id="staff-core">
<title>The FreeBSD Core Team</title>
@ -15,9 +14,7 @@
<para>(in alphabetical order by last name):</para>
<itemizedlist>
<listitem>
<para>&a.asami;</para>
</listitem>
@ -77,19 +74,15 @@
<listitem>
<para>&a.joerg;</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="staff-committers">
<title>The FreeBSD Developers</title>
<para>These are the people who have commit privileges and do the
engineering work on the FreeBSD source tree. All core team members
are also developers.</para>
engineering work on the FreeBSD source tree. All core team members are
also developers.</para>
<itemizedlist>
<listitem>
@ -579,52 +572,49 @@
<listitem>
<para>&a.archie;</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="staff-doc">
<title>The FreeBSD Documentation Project</title>
<para>The <ulink URL="http://www.freebsd.org/docproj.html">FreeBSD
Documentation Project</ulink> is responsible for a number of
different services, each service being run by an individual and his
Documentation Project</ulink> is responsible for a number of different
services, each service being run by an individual and his
<emphasis>deputies</emphasis> (if any):</para>
<variablelist>
<varlistentry><term>Documentation Project Manager</term>
<varlistentry>
<term>Documentation Project Manager</term>
<listitem>
<para>&a.nik;</para>
</listitem>
</varlistentry>
<varlistentry><term>Webmaster</term>
<varlistentry>
<term>Webmaster</term>
<listitem>
<para>&a.wosch;</para>
</listitem>
</varlistentry>
<varlistentry><term>Handbook &amp; FAQ Editor</term>
<varlistentry>
<term>Handbook &amp; FAQ Editor</term>
<listitem>
<para>&a.faq;</para>
</listitem>
</varlistentry>
<varlistentry><term>News Editor</term>
<varlistentry>
<term>News Editor</term>
<listitem>
<para>&a.nsj;</para>
<para><emphasis>Deputy:</emphasis> &a.john;</para>
</listitem>
</varlistentry>
@ -636,7 +626,8 @@
</listitem>
</varlistentry>
<varlistentry><term>Gallery Editor</term>
<varlistentry>
<term>Gallery Editor</term>
<listitem>
<para>&a.nsj;</para>
@ -662,28 +653,32 @@
</listitem>
</varlistentry>
<varlistentry><term>Style Police &amp; Art Director</term>
<varlistentry>
<term>Style Police &amp; Art Director</term>
<listitem>
<para>&a.opsys;</para>
</listitem>
</varlistentry>
<varlistentry><term>Database Engineer</term>
<varlistentry>
<term>Database Engineer</term>
<listitem>
<para>&a.mayo;</para>
</listitem>
</varlistentry>
<varlistentry><term>CGI Engineer</term>
<varlistentry>
<term>CGI Engineer</term>
<listitem>
<para>&a.stb;</para>
</listitem>
</varlistentry>
<varlistentry><term>Bottle Washing</term>
<varlistentry>
<term>Bottle Washing</term>
<listitem>
<para>&a.nsj;</para>
@ -698,36 +693,35 @@
</listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="staff-who">
<title>Who Is Responsible for What</title>
<variablelist>
<varlistentry><term>Principal Architect</term>
<varlistentry>
<term>Principal Architect</term>
<listitem>
<para>&a.dg;</para>
</listitem>
</varlistentry>
<varlistentry><term><ulink
url="http://www.freebsd.org/docproj/docproj.html">Documentation Project Manager</ulink></term>
<varlistentry>
<term><ulink
url="http://www.freebsd.org/docproj/docproj.html">Documentation
Project Manager</ulink></term>
<listitem>
<para>&a.nik;</para>
</listitem>
</varlistentry>
<varlistentry><term><link linkend="l10n">Internationalization</link></term>
<varlistentry>
<term><link linkend="l10n">Internationalization</link></term>
<listitem>
<para>&a.ache;</para>
</listitem>
</varlistentry>
@ -735,44 +729,45 @@
<listitem>
<para>&a.wollman;</para>
</listitem>
</varlistentry>
<varlistentry><term><link linkend="eresources-mail">Postmaster</link></term>
<varlistentry>
<term><link linkend="eresources-mail">Postmaster</link></term>
<listitem>
<para>&a.jmb;</para>
</listitem>
</varlistentry>
<varlistentry><term>Release Coordinator</term>
<varlistentry>
<term>Release Coordinator</term>
<listitem>
<para>&a.jkh;</para>
</listitem>
</varlistentry>
<varlistentry><term>Public Relations &amp; Corporate
Liaison</term>
<varlistentry>
<term>Public Relations &amp; Corporate Liaison</term>
<listitem>
<para>&a.jkh;</para>
</listitem>
</varlistentry>
<varlistentry><term><ulink url="http://www.freebsd.org/security/">Security Officer</ulink></term>
<varlistentry>
<term><ulink url="http://www.freebsd.org/security/">Security
Officer</ulink></term>
<listitem>
<para>&a.imp;</para>
</listitem>
</varlistentry>
<varlistentry><term><ulink url="http://www.freebsd.org/support.html#cvs">>Source Repository Managers</ulink></term>
<varlistentry>
<term><ulink url="http://www.freebsd.org/support.html#cvs">>Source
Repository Managers</ulink></term>
<listitem>
<para>Principal: &a.peter;</para>
@ -780,54 +775,54 @@
<para>Assistant: &a.jdp;</para>
<para>International (Crypto): &a.markm;</para>
</listitem>
</varlistentry>
<varlistentry><term><ulink url="http://www.freebsd.org/ports/">Ports Manager</ulink></term>
<listitem>
<para>&a.asami;</para>
</listitem>
</varlistentry>
<varlistentry><term>XFree86 Project, Inc. Liaison</term>
<listitem>
<para>&a.rich;</para>
</listitem>
</varlistentry>
<varlistentry><term><link linkend="eresources-news">Usenet Support</link></term>
<listitem>
<para>&a.joerg;</para>
</listitem>
</varlistentry>
<varlistentry><term><ulink url="http://www.freebsd.org/support.html#gnats">GNATS Administrator</ulink></term>
<listitem>
<para>&a.steve;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url="http://www.freebsd.org/internal/">Webmaster</ulink></term>
<term><ulink url="http://www.freebsd.org/ports/">Ports
Manager</ulink></term>
<listitem>
<para>&a.asami;</para>
</listitem>
</varlistentry>
<varlistentry>
<term>XFree86 Project, Inc. Liaison</term>
<listitem>
<para>&a.rich;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><link linkend="eresources-news">Usenet Support</link></term>
<listitem>
<para>&a.joerg;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url="http://www.freebsd.org/support.html#gnats">GNATS
Administrator</ulink></term>
<listitem>
<para>&a.steve;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink
url="http://www.freebsd.org/internal/">Webmaster</ulink></term>
<listitem>
<para>&a.wosch;</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
</chapter>
</chapter>
<!--
Local Variables:

11
en/handbook/x11/chapter.sgml
View file

@ -1,11 +1,10 @@
<chapter id="x11">
<chapter id="x11">
<title>The X Window System</title>
<para>Pending the completion of this section, please refer to
documentation supplied by the <ulink URL="http://www.xfree86.org/">The
XFree86 Project, Inc</ulink>.</para>
</chapter>
<para>Pending the completion of this section, please refer to documentation
supplied by the <ulink URL="http://www.xfree86.org/">The XFree86 Project,
Inc</ulink>.</para>
</chapter>
<!--
Local Variables:

6188
en_US.ISO8859-1/articles/contributing/article.sgml
View file

File diff suppressed because it is too large Load diff

540
en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml
View file

@ -1,95 +1,87 @@
<chapter id="kerneldebug">
<chapter id="kerneldebug">
<title>Kernel Debugging</title>
<para><emphasis>Contributed by &a.paul; and &a.joerg;</emphasis></para>
<sect1>
<title>Debugging a Kernel Crash Dump with <command>kgdb</command></title>
<para>Here are some instructions for getting kernel debugging working
on a crash dump. They assume that you have enough swap space for a
crash dump. If you have multiple swap partitions and the first one
is too small to hold the dump, you can configure your kernel to use
an alternate dump device (in the <literal>config
kernel</literal> line), or you can specify an alternate using the
&man.dumpon.8; command. The best way to use &man.dumpon.8; is to set the <literal>dumpdev</literal> variable in
<para>Here are some instructions for getting kernel debugging working on a
crash dump. They assume that you have enough swap space for a crash
dump. If you have multiple swap partitions and the first one is too
small to hold the dump, you can configure your kernel to use an
alternate dump device (in the <literal>config kernel</literal> line), or
you can specify an alternate using the
&man.dumpon.8; command. The best way to use &man.dumpon.8; is to set
the <literal>dumpdev</literal> variable in
<filename>/etc/rc.conf</filename>. Typically you want to specify one of
the swap devices specified in <filename>/etc/fstab</filename>.
Dumps to non-swap devices, tapes for example,
are currently not supported. Config your kernel using
<command>config -g</command>. See <link linkend="kernelconfig">Kernel
Configuration</link> for
details on configuring the FreeBSD kernel.</para>
the swap devices specified in <filename>/etc/fstab</filename>. Dumps to
non-swap devices, tapes for example, are currently not supported. Config
your kernel using <command>config -g</command>. See <link
linkend="kernelconfig">Kernel Configuration</link> for details on
configuring the FreeBSD kernel.</para>
<para>Use the &man.dumpon.8; command to tell the kernel
where to dump to (note that this will have to be done after
configuring the partition in question as swap space via
&man.swapon.8;). This is normally arranged via
<filename>/etc/rc.conf</filename> and <filename>/etc/rc</filename>.
Alternatively, you can hard-code the dump device via the <literal>dump</literal>
clause in the <literal>config</literal> line of your kernel config file. This is
deprecated and should be used only if you want a crash dump from a
kernel that crashes during booting.</para>
<para>Use the &man.dumpon.8; command to tell the kernel where to dump to
(note that this will have to be done after configuring the partition in
question as swap space via &man.swapon.8;). This is normally arranged
via <filename>/etc/rc.conf</filename> and <filename>/etc/rc</filename>.
Alternatively, you can hard-code the dump device via the
<literal>dump</literal> clause in the <literal>config</literal> line of
your kernel config file. This is deprecated and should be used only if
you want a crash dump from a kernel that crashes during booting.</para>
<note>
<para>In the following, the term <command>kgdb</command> refers to
<command>gdb</command> run in &ldquo;kernel debug mode&rdquo;. This can be
accomplished by either starting the <command>gdb</command> with
the option <option>-k</option>, or by linking and starting it
under the name <command>kgdb</command>. This is not being done by
default, however, and the idea is basically deprecated since the
GNU folks do not like their tools to behave differently when
called by another name. This feature may well be discontinued in
further releases.</para>
<command>gdb</command> run in &ldquo;kernel debug mode&rdquo;. This
can be accomplished by either starting the <command>gdb</command> with
the option <option>-k</option>, or by linking and starting it under
the name <command>kgdb</command>. This is not being done by default,
however, and the idea is basically deprecated since the GNU folks do
not like their tools to behave differently when called by another
name. This feature may well be discontinued in further
releases.</para>
</note>
<para>When the kernel has been built make a copy of it, say
<filename>kernel.debug</filename>, and then run <command>strip
-d</command> on the original. Install the original as normal. You
may also install the unstripped kernel, but symbol table lookup time
for some programs will drastically increase, and since the whole
kernel is loaded entirely at boot time and cannot be swapped out
later, several megabytes of physical memory will be wasted.</para>
may also install the unstripped kernel, but symbol table lookup time for
some programs will drastically increase, and since the whole kernel is
loaded entirely at boot time and cannot be swapped out later, several
megabytes of physical memory will be wasted.</para>
<para>If you are testing a new kernel, for example by typing the new
kernel's name at the boot prompt, but need to boot a different one
in order to get your system up and running again, boot it only into
single user state using the <option>-s</option> flag at the boot
prompt, and then perform the following steps:</para>
kernel's name at the boot prompt, but need to boot a different one in
order to get your system up and running again, boot it only into single
user state using the <option>-s</option> flag at the boot prompt, and
then perform the following steps:</para>
<screen>&prompt.root; <userinput>fsck -p</userinput>
&prompt.root; <userinput>mount -a -t ufs</userinput> # so your file system for /var/crash is writable
&prompt.root; <userinput>savecore -N /kernel.panicked /var/crash</userinput>
&prompt.root; <userinput>exit</userinput> # ...to multi-user</screen>
<para>This instructs &man.savecore.8; to
use another kernel for symbol name extraction. It would otherwise
default to the currently running kernel and most likely not do
anything at all since the crash dump and the kernel symbols
differ.</para>
<para>This instructs &man.savecore.8; to use another kernel for symbol
name extraction. It would otherwise default to the currently running
kernel and most likely not do anything at all since the crash dump and
the kernel symbols differ.</para>
<para>Now, after a crash dump, go to
<filename>/sys/compile/WHATEVER</filename> and run <command>kgdb</command>. From <command>kgdb</command>
do:
<filename>/sys/compile/WHATEVER</filename> and run
<command>kgdb</command>. From <command>kgdb</command> do:
<screen><userinput>symbol-file kernel.debug</userinput>
<userinput>exec-file /var/crash/kernel.0</userinput>
<userinput>core-file /var/crash/vmcore.0</userinput></screen>
and voila, you can debug the crash dump using the kernel sources just
like you can for any other program.</para>
and voila, you can debug the crash dump using the
kernel sources just like you can for any other program.</para>
<para>Here is a script log of a <command>kgdb</command>
session illustrating the procedure. Long lines have been folded to
improve readability, and the lines are numbered for reference.
Despite this, it is a real-world error trace taken during the
development of the pcvt console driver.</para>
<para>Here is a script log of a <command>kgdb</command> session
illustrating the procedure. Long lines have been folded to improve
readability, and the lines are numbered for reference. Despite this, it
is a real-world error trace taken during the development of the pcvt
console driver.</para>
<screen> 1:Script started on Fri Dec 30 23:15:22 1994
2:&prompt.root; <userinput>cd /sys/compile/URIAH</userinput>
@ -172,68 +164,65 @@ Dumps to non-swap devices, tapes for example,
79:
80:Script done on Fri Dec 30 23:18:04 1994</screen>
<para>Comments to the above script:</para>
<variablelist>
<varlistentry><term>line 6:</term>
<listitem>
<para>This is a dump taken from within DDB (see below), hence
the panic comment &ldquo;because you said to!&rdquo;, and a rather
long stack trace; the initial reason for going into DDB has
been a page fault trap though.</para>
<varlistentry>
<term>line 6:</term>
<listitem>
<para>This is a dump taken from within DDB (see below), hence the
panic comment &ldquo;because you said to!&rdquo;, and a rather
long stack trace; the initial reason for going into DDB has been a
page fault trap though.</para>
</listitem>
</varlistentry>
<varlistentry><term>line 20:</term>
<varlistentry>
<term>line 20:</term>
<listitem>
<para>This is the location of function
<function>trap()</function> in the stack trace.</para>
<para>This is the location of function <function>trap()</function>
in the stack trace.</para>
</listitem>
</varlistentry>
<varlistentry><term>line 36:</term>
<varlistentry>
<term>line 36:</term>
<listitem>
<para>Force usage of a new stack frame; this is no longer
necessary now. The stack frames are supposed to point to
the right locations now, even in case of a trap. (I do not
have a new core dump handy &lt;g&gt;, my kernel has not
panicked for a rather long time.) From looking at the code
in source line 403, there is a high probability that either
the pointer access for &ldquo;tp&rdquo; was messed up, or the array
access was out of bounds.</para>
<para>Force usage of a new stack frame; this is no longer necessary
now. The stack frames are supposed to point to the right
locations now, even in case of a trap. (I do not have a new core
dump handy &lt;g&gt;, my kernel has not panicked for a rather long
time.) From looking at the code in source line 403, there is a
high probability that either the pointer access for
&ldquo;tp&rdquo; was messed up, or the array access was out of
bounds.</para>
</listitem>
</varlistentry>
<varlistentry><term>line 52:</term>
<varlistentry>
<term>line 52:</term>
<listitem>
<para>The pointer looks suspicious, but happens to be a valid
address.</para>
</listitem>
</varlistentry>
<varlistentry><term>line 56:</term>
<varlistentry>
<term>line 56:</term>
<listitem>
<para>However, it obviously points to garbage, so we have
found our error! (For those unfamiliar with that particular
piece of code: <literal>tp-&gt;t_line</literal>
refers to the line discipline of the console device here,
which must be a rather small integer number.)</para>
<para>However, it obviously points to garbage, so we have found our
error! (For those unfamiliar with that particular piece of code:
<literal>tp-&gt;t_line</literal> refers to the line discipline of
the console device here, which must be a rather small integer
number.)</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1>
@ -244,10 +233,8 @@ Dumps to non-swap devices, tapes for example,
option to the <command>ddd</command> command line you would use
normally. For example;</para>
<screen>&prompt.root; <userinput>ddd -k /var/crash/kernel.0 /var/crash/vmcore.0</userinput></screen>
<para>You should then be able to go about looking at the crash dump using
<command>ddd</command>'d graphical interface.</para>
</sect1>
@ -255,124 +242,115 @@ Dumps to non-swap devices, tapes for example,
<sect1>
<title>Post-mortem Analysis of a Dump</title>
<para>What do you do if a kernel dumped core but you did not expect
it, and it is therefore not compiled using <command>config
-g</command>? Not everything is lost here. Do not panic!</para>
<para>What do you do if a kernel dumped core but you did not expect it,
and it is therefore not compiled using <command>config -g</command>? Not
everything is lost here. Do not panic!</para>
<para>Of course, you still need to enable crash dumps. See above on
the options you have to specify in order to do this.</para>
<para>Of course, you still need to enable crash dumps. See above on the
options you have to specify in order to do this.</para>
<para>Go to your kernel compile directory, and edit the line
containing <literal>COPTFLAGS?=-O</literal>. Add the
<option>-g</option> option there (but <emphasis>do not</emphasis>
change anything on the level of optimization). If you do already
know roughly the probable location of the failing piece of code
(e.g., the <devicename>pcvt</devicename> driver in the example
above), remove all the object files for this code. Rebuild the
kernel. Due to the time stamp change on the Makefile, there will be
some other object files rebuild, for example
<para>Go to your kernel compile directory, and edit the line containing
<literal>COPTFLAGS?=-O</literal>. Add the <option>-g</option> option
there (but <emphasis>do not</emphasis> change anything on the level of
optimization). If you do already know roughly the probable location of
the failing piece of code (e.g., the <devicename>pcvt</devicename>
driver in the example above), remove all the object files for this code.
Rebuild the kernel. Due to the time stamp change on the Makefile, there
will be some other object files rebuild, for example
<filename>trap.o</filename>. With a bit of luck, the added
<option>-g</option> option will not change anything for the
generated code, so you will finally get a new kernel with similar
code to the faulting one but some debugging symbols. You should at
least verify the old and new sizes with the
&man.size.1; command. If there is a mismatch, you
probably need to give up here.</para>
<option>-g</option> option will not change anything for the generated
code, so you will finally get a new kernel with similar code to the
faulting one but some debugging symbols. You should at least verify the
old and new sizes with the
&man.size.1; command. If there is a mismatch, you probably need to
give up here.</para>
<para>Go and examine the dump as described above. The debugging
symbols might be incomplete for some places, as can be seen in the
stack trace in the example above where some functions are displayed
without line numbers and argument lists. If you need more debugging
symbols, remove the appropriate object files and repeat the
<command>kgdb</command> session until you know
enough.</para>
<para>All this is not guaranteed to work, but it will do it fine in
most cases.</para>
<para>Go and examine the dump as described above. The debugging symbols
might be incomplete for some places, as can be seen in the stack trace
in the example above where some functions are displayed without line
numbers and argument lists. If you need more debugging symbols, remove
the appropriate object files and repeat the <command>kgdb</command>
session until you know enough.</para>
<para>All this is not guaranteed to work, but it will do it fine in most
cases.</para>
</sect1>
<sect1>
<title>On-line Kernel Debugging Using DDB</title>
<para>While <command>kgdb</command> as an offline debugger
provides a very high level of user interface, there are some things
it cannot do. The most important ones being breakpointing and
single-stepping kernel code.</para>
<para>While <command>kgdb</command> as an offline debugger provides a very
high level of user interface, there are some things it cannot do. The
most important ones being breakpointing and single-stepping kernel
code.</para>
<para>If you need to do low-level debugging on your kernel, there is
an on-line debugger available called DDB. It allows to setting
<para>If you need to do low-level debugging on your kernel, there is an
on-line debugger available called DDB. It allows to setting
breakpoints, single-steping kernel functions, examining and changing
kernel variables, etc. However, it cannot access kernel source
files, and only has access to the global and static symbols, not to
the full debug information like <command>kgdb</command>.</para>
kernel variables, etc. However, it cannot access kernel source files,
and only has access to the global and static symbols, not to the full
debug information like <command>kgdb</command>.</para>
<para>To configure your kernel to include DDB, add the option line
<programlisting>
options DDB</programlisting> to your config file, and rebuild. (See <link
linkend="kernelconfig">Kernel Configuration</link> for details on configuring the
FreeBSD kernel.</para>
options DDB</programlisting>
to your config file, and rebuild. (See <link
linkend="kernelconfig">Kernel Configuration</link> for details on
configuring the FreeBSD kernel.</para>
<note>
<para>Note that if you have an older version of the boot blocks,
your debugger symbols might not be loaded at all. Update the boot
blocks; the recent ones load the DDB symbols
automagically.)</para>
<para>Note that if you have an older version of the boot blocks, your
debugger symbols might not be loaded at all. Update the boot blocks;
the recent ones load the DDB symbols automagically.)</para>
</note>
<para>Once your DDB kernel is running, there are several ways to enter
DDB. The first, and earliest way is to type the boot flag
<option>-d</option> right at the boot prompt. The kernel will start
up in debug mode and enter DDB prior to any device probing. Hence
you can even debug the device probe/attach functions.</para>
<option>-d</option> right at the boot prompt. The kernel will start up
in debug mode and enter DDB prior to any device probing. Hence you can
even debug the device probe/attach functions.</para>
<para>The second scenario is a hot-key on the keyboard, usually
Ctrl-Alt-ESC. For syscons, this can be remapped; some of the
distributed maps do this, so watch out. There is an option available
for serial consoles that allows the use of a serial line BREAK on
the console line to enter DDB (<literal>options
BREAK_TO_DEBUGGER</literal> in the kernel config file). It is
not the default since there are a lot of crappy serial adapters
around that gratuitously generate a BREAK condition, for example
when pulling the cable.</para>
for serial consoles that allows the use of a serial line BREAK on the
console line to enter DDB (<literal>options BREAK_TO_DEBUGGER</literal>
in the kernel config file). It is not the default since there are a lot
of crappy serial adapters around that gratuitously generate a BREAK
condition, for example when pulling the cable.</para>
<para>The third way is that any panic condition will branch to DDB if
the kernel is configured to use it. For this reason, it is not
wise to configure a kernel with DDB for a machine running
unattended.</para>
<para>The DDB commands roughly resemble some <command>gdb</command> commands. The first thing you probably
need to do is to set a breakpoint:</para>
<para>The third way is that any panic condition will branch to DDB if the
kernel is configured to use it. For this reason, it is not wise to
configure a kernel with DDB for a machine running unattended.</para>
<para>The DDB commands roughly resemble some <command>gdb</command>
commands. The first thing you probably need to do is to set a
breakpoint:</para>
<screen><userinput>b function-name</userinput>
<userinput>b address</userinput></screen>
<para>Numbers are taken hexadecimal by default, but to make them distinct
from symbol names; hexadecimal numbers starting with the letters
<literal>a-f</literal> need to be preceded with <literal>0x</literal>
(this is optional for other numbers). Simple expressions are allowed,
for example: <literal>function-name + 0x103</literal>.</para>
<para>Numbers are taken hexadecimal by default, but to make them
distinct from symbol names; hexadecimal numbers starting with the
letters <literal>a-f</literal> need to be preceded with
<literal>0x</literal> (this is optional for other numbers). Simple
expressions are allowed, for example: <literal>function-name +
0x103</literal>.</para>
<para>To continue the operation of an interrupted kernel, simply type:</para>
<para>To continue the operation of an interrupted kernel, simply
type:</para>
<screen><userinput>c</userinput></screen>
<para>To get a stack trace, use:</para>
<screen><userinput>trace</userinput></screen>
<note>
<para>Note that when entering DDB via a hot-key, the kernel is
currently servicing an interrupt, so the stack trace might be not
of much use for you.</para>
<para>Note that when entering DDB via a hot-key, the kernel is currently
servicing an interrupt, so the stack trace might be not of much use
for you.</para>
</note>
<para>If you want to remove a breakpoint, use</para>
@ -381,178 +359,143 @@ options DDB</programlisting> to your config file, and rebuild. (See <link
<screen><userinput>del</userinput>
<userinput>del address-expression</userinput></screen>
<para>The first form will be accepted immediately after
a breakpoint hit, and deletes the current breakpoint. The second
form can remove any breakpoint, but you need to specify the exact
address; this can be obtained from:</para>
<para>The first form will be accepted immediately after a breakpoint hit,
and deletes the current breakpoint. The second form can remove any
breakpoint, but you need to specify the exact address; this can be
obtained from:</para>
<screen><userinput>show b</userinput></screen>
<para>To single-step the kernel, try:</para>
<screen><userinput>s</userinput></screen>
<para>This will step into functions, but you can make
DDB trace them until the matching return statement is reached by:</para>
<para>This will step into functions, but you can make DDB trace them until
the matching return statement is reached by:</para>
<screen><userinput>n</userinput></screen>
<note>
<para>This is different from <command>gdb</command>'s <command>next</command>
statement; it is like <command>gdb</command>'s <command>finish</command>.</para>
<para>This is different from <command>gdb</command>'s
<command>next</command> statement; it is like <command>gdb</command>'s
<command>finish</command>.</para>
</note>
<para>To examine data from memory, use (for example):
<screen><userinput>x/wx 0xf0133fe0,40</userinput>
<userinput>x/hd db_symtab_space</userinput>
<userinput>x/bc termbuf,10</userinput>
<userinput>x/s stringbuf</userinput></screen>
for word/halfword/byte access, and
hexadecimal/decimal/character/ string display. The number after the
comma is the object count. To display the next 0x10 items, simply
use:</para>
for word/halfword/byte access, and hexadecimal/decimal/character/ string
display. The number after the comma is the object count. To display
the next 0x10 items, simply use:</para>
<screen><userinput>x ,10</userinput></screen>
<para>Similarly, use
<screen><userinput>x/ia foofunc,10</userinput></screen>
to disassemble the first 0x10 instructions of
<function>foofunc</function>, and display them along with
their offset from the beginning of <function>foofunc</function>.</para>
<function>foofunc</function>, and display them along with their offset
from the beginning of <function>foofunc</function>.</para>
<para>To modify memory, use the write command:</para>
<screen><userinput>w/b termbuf 0xa 0xb 0</userinput>
<userinput>w/w 0xf0010030 0 0</userinput></screen>
<para>The command modifier
(<literal>b</literal>/<literal>h</literal>/<literal>w</literal>) specifies the size of the data to be
written, the first following expression is the address to write to
and the remainder is interpreted as data to write to successive
memory locations.</para>
(<literal>b</literal>/<literal>h</literal>/<literal>w</literal>)
specifies the size of the data to be written, the first following
expression is the address to write to and the remainder is interpreted
as data to write to successive memory locations.</para>
<para>If you need to know the current registers, use:</para>
<screen><userinput>show reg</userinput></screen>
<para>Alternatively, you can display a single register
value by e.g.
<para>Alternatively, you can display a single register value by e.g.
<screen><userinput>p $eax</userinput></screen>
and modify it by:</para>
<screen><userinput>set $eax new-value</userinput></screen>
<para>Should you need to call some kernel functions from DDB, simply
say:</para>
<screen><userinput>call func(arg1, arg2, ...)</userinput></screen>
<para>The return value will be printed.</para>
<para>For a &man.ps.1; style summary of all running
processes, use:</para>
<para>For a &man.ps.1; style summary of all running processes, use:</para>
<screen><userinput>ps</userinput></screen>
<para>Now you have now examined why your kernel failed, and you wish
to reboot. Remember that, depending on the severity of previous
malfunctioning, not all parts of the kernel might still be working
as expected. Perform one of the following actions to shut down and
reboot your system:</para>
<para>Now you have now examined why your kernel failed, and you wish to
reboot. Remember that, depending on the severity of previous
malfunctioning, not all parts of the kernel might still be working as
expected. Perform one of the following actions to shut down and reboot
your system:</para>
<screen><userinput>call diediedie()</userinput></screen>
<para>This will cause your kernel to dump core and reboot, so you can
later analyze the core on a higher level with kgdb. This command
usually must be followed by another <command>continue</command> statement. There is now an alias for
this: <command>panic</command>.</para>
usually must be followed by another <command>continue</command>
statement. There is now an alias for this:
<command>panic</command>.</para>
<screen><userinput>call boot(0)</userinput></screen>
<para>Which might be a good way to cleanly shut down the
running system, <function>sync()</function> all disks, and finally
reboot. As long as the disk and file system interfaces of the
kernel are not damaged, this might be a good way for an almost clean
shutdown.</para>
<para>Which might be a good way to cleanly shut down the running system,
<function>sync()</function> all disks, and finally reboot. As long as
the disk and file system interfaces of the kernel are not damaged, this
might be a good way for an almost clean shutdown.</para>
<screen><userinput>call cpu_reset()</userinput></screen>
<para>is the final way out of disaster and almost the
same as hitting the Big Red Button.</para>
<para>is the final way out of disaster and almost the same as hitting the
Big Red Button.</para>
<para>If you need a short command summary, simply type:</para>
<screen><userinput>help</userinput></screen>
<para>However, it is highly recommended to have a
printed copy of the &man.ddb.4; manual page
ready for a debugging session. Remember that it is hard to read the
on-line manual while single-stepping the kernel.</para>
<para>However, it is highly recommended to have a printed copy of the
&man.ddb.4; manual page ready for a debugging
session. Remember that it is hard to read the on-line manual while
single-stepping the kernel.</para>
</sect1>
<sect1>
<title>On-line Kernel Debugging Using Remote GDB</title>
<para>This feature has been supported since FreeBSD 2.2, and it's
actually a very neat one.</para>
<para>This feature has been supported since FreeBSD 2.2, and it's actually
a very neat one.</para>
<para>GDB has already supported <emphasis>remote debugging</emphasis>
for a long time. This is done using a very simple protocol along a
serial line. Unlike the other methods described above, you will
need two machines for doing this. One is the host providing the
debugging environment, including all the sources, and a copy of the
kernel binary with all the symbols in it, and the other one is the
target machine that simply runs a similar copy of the very same
kernel (but stripped of the debugging information).</para>
<para>GDB has already supported <emphasis>remote debugging</emphasis> for
a long time. This is done using a very simple protocol along a serial
line. Unlike the other methods described above, you will need two
machines for doing this. One is the host providing the debugging
environment, including all the sources, and a copy of the kernel binary
with all the symbols in it, and the other one is the target machine that
simply runs a similar copy of the very same kernel (but stripped of the
debugging information).</para>
<para>You should configure the kernel in question with <command>config
-g</command>, include <option>DDB</option> into the
configuration, and compile it as usual. This gives a large blurb of
a binary, due to the debugging information. Copy this kernel to the
target machine, strip the debugging symbols off with <command>strip
-x</command>, and boot it using the <option>-d</option> boot
option. Connect the first serial line of the target machine to any
serial line of the debugging host. Now, on the debugging machine,
go to the compile directory of the target kernel, and start gdb:</para>
-g</command>, include <option>DDB</option> into the configuration, and
compile it as usual. This gives a large blurb of a binary, due to the
debugging information. Copy this kernel to the target machine, strip
the debugging symbols off with <command>strip -x</command>, and boot it
using the <option>-d</option> boot option. Connect the first serial
line of the target machine to any serial line of the debugging host.
Now, on the debugging machine, go to the compile directory of the target
kernel, and start gdb:</para>
<screen>&prompt.user; <userinput>gdb -k kernel</userinput>
GDB is free software and you are welcome to distribute copies of it
@ -562,94 +505,77 @@ GDB 4.16 (i386-unknown-freebsd),
Copyright 1996 Free Software Foundation, Inc...
<prompt>(kgdb)</prompt> </screen>
<para>Initialize the remote debugging session (assuming the first
serial port is being used) by:</para>
<para>Initialize the remote debugging session (assuming the first serial
port is being used) by:</para>
<screen><prompt>(kgdb)</prompt> <userinput>target remote /dev/cuaa0</userinput></screen>
<para>Now, on the target host (the one that entered DDB right before
even starting the device probe), type:</para>
<para>Now, on the target host (the one that entered DDB right before even
starting the device probe), type:</para>
<screen>Debugger("Boot flags requested debugger")
Stopped at Debugger+0x35: movb $0, edata+0x51bc
<prompt>db&gt;</prompt> <userinput>gdb</userinput></screen>
<para>DDB will respond with:</para>
<screen>Next trap will enter GDB remote protocol mode</screen>
<para>Every time you type <command>gdb</command>, the mode will be toggled between
remote GDB and local DDB. In order to force a next trap
immediately, simply type <command>s</command> (step). Your hosting GDB will now
gain control over the target kernel:</para>
<para>Every time you type <command>gdb</command>, the mode will be toggled
between remote GDB and local DDB. In order to force a next trap
immediately, simply type <command>s</command> (step). Your hosting GDB
will now gain control over the target kernel:</para>
<screen>Remote debugging using /dev/cuaa0
Debugger (msg=0xf01b0383 "Boot flags requested debugger")
at ../../i386/i386/db_interface.c:257
<prompt>(kgdb)</prompt></screen>
<para>You can use this session almost as any other GDB session, including
full access to the source, running it in gud-mode inside an Emacs window
(which gives you an automatic source code display in another Emacs
window) etc.</para>
<para>You can use this session almost as any other GDB session,
including full access to the source, running it in gud-mode inside
an Emacs window (which gives you an automatic source code display in
another Emacs window) etc.</para>
<para>Remote GDB can also be used to debug LKMs. First build the LKM
with debugging symbols:</para>
<para>Remote GDB can also be used to debug LKMs. First build the LKM with
debugging symbols:</para>
<screen>&prompt.root; <userinput>cd /usr/src/lkm/linux</userinput>
&prompt.root; <userinput>make clean; make COPTS=-g</userinput></screen>
<para>Then install this version of the module on the target machine,
load it and use <command>modstat</command> to find out
where it was loaded:</para>
<para>Then install this version of the module on the target machine, load
it and use <command>modstat</command> to find out where it was
loaded:</para>
<screen>&prompt.root; <userinput>linux</userinput>
&prompt.root; <userinput>modstat</userinput>
Type Id Off Loadaddr Size Info Rev Module Name
EXEC 0 4 f5109000 001c f510f010 1 linux_mod</screen>
<para>Take the load address of the module and add 0x20 (probably to
account for the a.out header). This is the address that the module
code was relocated to. Use the <command>add-symbol-file</command> command in GDB to tell the
debugger about the module:</para>
account for the a.out header). This is the address that the module code
was relocated to. Use the <command>add-symbol-file</command> command in
GDB to tell the debugger about the module:</para>
<screen><prompt>(kgdb)</prompt> <userinput>add-symbol-file /usr/src/lkm/linux/linux_mod.o 0xf5109020</userinput>
add symbol table from file "/usr/src/lkm/linux/linux_mod.o" at
text_addr = 0xf5109020? (y or n) <userinput>y</userinput>
<prompt>(kgdb)</prompt></screen>
<para>You now have access to all the symbols in the LKM.</para>
</sect1>
<sect1>
<title>Debugging a Console Driver</title>
<para>Since you need a console driver to run DDB on, things are more
complicated if the console driver itself is failing. You might
remember the use of a serial console (either with modified boot
blocks, or by specifying <option>-h</option> at the <prompt>Boot:</prompt> prompt), and hook up a standard terminal
onto your first serial port. DDB works on any configured console
driver, of course also on a serial console.</para>
complicated if the console driver itself is failing. You might remember
the use of a serial console (either with modified boot blocks, or by
specifying <option>-h</option> at the <prompt>Boot:</prompt> prompt),
and hook up a standard terminal onto your first serial port. DDB works
on any configured console driver, of course also on a serial
console.</para>
</sect1>
</chapter>
</chapter>
<!--
Local Variables:

271
en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml
View file

@ -1,11 +1,10 @@
<chapter id="policies">
<chapter id="policies">
<title>Source Tree Guidelines and Policies</title>
<para><emphasis>Contributed by &a.phk;.</emphasis></para>
<para>This chapter documents various guidelines and policies in force
for the FreeBSD source tree.</para>
<para>This chapter documents various guidelines and policies in force for
the FreeBSD source tree.</para>
<sect1 id="policies-maintainer">
<title><makevar>MAINTAINER</makevar> on Makefiles</title>
@ -13,36 +12,33 @@
<para>June 1996.</para>
<para>If a particular portion of the FreeBSD distribution is being
maintained by a person or group of persons, they can communicate
this fact to the world by adding a
maintained by a person or group of persons, they can communicate this
fact to the world by adding a
<programlisting>
MAINTAINER= email-addresses</programlisting>
line to the <filename>Makefile</filename>s covering this portion
of the source tree.</para>
line to the <filename>Makefile</filename>s covering this portion of the
source tree.</para>
<para>The semantics of this are as follows:</para>
<para>The maintainer owns and is responsible for that code. This
means that he is responsible for fixing bugs and answer problem
reports pertaining to that piece of the code, and in the case of
contributed software, for tracking new versions, as
appropriate.</para>
<para>The maintainer owns and is responsible for that code. This means
that he is responsible for fixing bugs and answer problem reports
pertaining to that piece of the code, and in the case of contributed
software, for tracking new versions, as appropriate.</para>
<para>Changes to directories which have a maintainer defined shall be
sent to the maintainer for review before being committed. Only if
the maintainer does not respond for an unacceptable period of time,
to several emails, will it be acceptable to commit changes without
review by the maintainer. However, it is suggested that you try and
have the changes reviewed by someone else if at all
possible.</para>
<para>Changes to directories which have a maintainer defined shall be sent
to the maintainer for review before being committed. Only if the
maintainer does not respond for an unacceptable period of time, to
several emails, will it be acceptable to commit changes without review
by the maintainer. However, it is suggested that you try and have the
changes reviewed by someone else if at all possible.</para>
<para>It is of course not acceptable to add a person or group as
maintainer unless they agree to assume this duty. On the other hand
it doesn't have to be a committer and it can easily be a group of
maintainer unless they agree to assume this duty. On the other hand it
doesn't have to be a committer and it can easily be a group of
people.</para>
</sect1>
<sect1>
@ -52,31 +48,31 @@ MAINTAINER= email-addresses</programlisting>
<para>June 1996.</para>
<para>Some parts of the FreeBSD distribution consist of software that
is actively being maintained outside the FreeBSD project. For
historical reasons, we call this <emphasis>contributed</emphasis>
software. Some examples are perl, gcc and patch.</para>
<para>Some parts of the FreeBSD distribution consist of software that is
actively being maintained outside the FreeBSD project. For historical
reasons, we call this <emphasis>contributed</emphasis> software. Some
examples are perl, gcc and patch.</para>
<para>Over the last couple of years, various methods have been used in
dealing with this type of software and all have some number of
advantages and drawbacks. No clear winner has emerged.</para>
<para>Since this is the case, after some debate one of these methods
has been selected as the &ldquo;official&rdquo; method and will be required for
future imports of software of this kind. Furthermore, it is
strongly suggested that existing contributed software converge on
this model over time, as it has significant advantages over the old
method, including the ability to easily obtain diffs relative to the
&ldquo;official&rdquo; versions of the source by everyone (even without cvs
access). This will make it significantly easier to return changes
<para>Since this is the case, after some debate one of these methods has
been selected as the &ldquo;official&rdquo; method and will be required
for future imports of software of this kind. Furthermore, it is
strongly suggested that existing contributed software converge on this
model over time, as it has significant advantages over the old method,
including the ability to easily obtain diffs relative to the
&ldquo;official&rdquo; versions of the source by everyone (even without
cvs access). This will make it significantly easier to return changes
to the primary developers of the contributed software.</para>
<para>Ultimately, however, it comes down to the people actually doing
the work. If using this model is particularly unsuited to the
package being dealt with, exceptions to these rules may be granted
only with the approval of the core team and with the general
consensus of the other developers. The ability to maintain the
package in the future will be a key issue in the decisions.</para>
<para>Ultimately, however, it comes down to the people actually doing the
work. If using this model is particularly unsuited to the package being
dealt with, exceptions to these rules may be granted only with the
approval of the core team and with the general consensus of the other
developers. The ability to maintain the package in the future will be a
key issue in the decisions.</para>
<note>
<para>Because of some unfortunate design limitations with the RCS file
@ -93,76 +89,72 @@ MAINTAINER= email-addresses</programlisting>
language will be used as example of how this model works:</para>
<para><filename>src/contrib/tcl</filename> contains the source as
distributed by the maintainers of this package. Parts that are
entirely not applicable for FreeBSD can be removed. In the case of
Tcl, the <filename>mac</filename>, <filename>win</filename> and
<filename>compat</filename> subdirectories were eliminated before
the import</para>
distributed by the maintainers of this package. Parts that are entirely
not applicable for FreeBSD can be removed. In the case of Tcl, the
<filename>mac</filename>, <filename>win</filename> and
<filename>compat</filename> subdirectories were eliminated before the
import</para>
<para><filename>src/lib/libtcl</filename> contains only a "bmake style"
<filename>Makefile</filename> that uses the standard
<filename>bsd.lib.mk</filename> makefile rules to produce the
library and install the documentation.</para>
<filename>bsd.lib.mk</filename> makefile rules to produce the library
and install the documentation.</para>
<para><filename>src/usr.bin/tclsh</filename> contains only a bmake style
<filename>Makefile</filename> which will produce and install the
<command>tclsh</command> program and its associated man-pages using the standard
<filename>bsd.prog.mk</filename> rules.</para>
<command>tclsh</command> program and its associated man-pages using the
standard <filename>bsd.prog.mk</filename> rules.</para>
<para><filename>src/tools/tools/tcl_bmake</filename> contains a couple of
shell-scripts that can be of help when the tcl software needs
updating. These are not part of the built or installed
software.</para>
shell-scripts that can be of help when the tcl software needs updating.
These are not part of the built or installed software.</para>
<para>The important thing here is that the
<filename>src/contrib/tcl</filename> directory is created according
to the rules: It is supposed to contain the sources as distributed
(on a proper CVS vendor-branch and without RCS keyword expansion) with as few FreeBSD-specific changes
as possible. The 'easy-import' tool on freefall will assist in
doing the import, but if there are any doubts on how to go about it,
it is imperative that you ask first and not blunder ahead and hope
it &ldquo;works out&rdquo;. CVS is not forgiving of import accidents and a fair
amount of effort is required to back out major mistakes.</para>
<filename>src/contrib/tcl</filename> directory is created according to
the rules: It is supposed to contain the sources as distributed (on a
proper CVS vendor-branch and without RCS keyword expansion) with as few
FreeBSD-specific changes as possible. The 'easy-import' tool on
freefall will assist in doing the import, but if there are any doubts on
how to go about it, it is imperative that you ask first and not blunder
ahead and hope it &ldquo;works out&rdquo;. CVS is not forgiving of
import accidents and a fair amount of effort is required to back out
major mistakes.</para>
<para>Because of the previously mentioned design limitations with CVS's vendor
branches, it is required that &ldquo;official&rdquo; patches from the vendor be
applied to the original distributed sources and the result
re-imported onto the vendor branch again. Official patches should
never be patched into the FreeBSD checked out version and
"committed", as this destroys the vendor branch coherency and makes
importing future versions rather difficult as there will be
conflicts.</para>
<para>Because of the previously mentioned design limitations with CVS's
vendor branches, it is required that &ldquo;official&rdquo; patches from
the vendor be applied to the original distributed sources and the result
re-imported onto the vendor branch again. Official patches should never
be patched into the FreeBSD checked out version and "committed", as this
destroys the vendor branch coherency and makes importing future versions
rather difficult as there will be conflicts.</para>
<para>Since many packages contain files that are meant for
compatibility with other architectures and environments that
FreeBSD, it is permissible to remove parts of the distribution tree
that are of no interest to FreeBSD in order to save space. Files
containing copyright notices and release-note kind of information
applicable to the remaining files shall <emphasis>not</emphasis> be
removed.</para>
<para>Since many packages contain files that are meant for compatibility
with other architectures and environments that FreeBSD, it is
permissible to remove parts of the distribution tree that are of no
interest to FreeBSD in order to save space. Files containing copyright
notices and release-note kind of information applicable to the remaining
files shall <emphasis>not</emphasis> be removed.</para>
<para>If it seems easier, the <command>bmake</command> <filename>Makefile</filename>s
can be produced from the dist tree automatically by some utility,
something which would hopefully make it even easier to upgrade to a
new version. If this is done, be sure to check in such utilities
(as necessary) in the <filename>src/tools</filename> directory along
with the port itself so that it is available to future
maintainers.</para>
<para>In the <filename>src/contrib/tcl</filename> level directory, a
file called <filename>FREEBSD-upgrade</filename> should be added and
it should states things like:</para>
<para>If it seems easier, the <command>bmake</command>
<filename>Makefile</filename>s can be produced from the dist tree
automatically by some utility, something which would hopefully make it
even easier to upgrade to a new version. If this is done, be sure to
check in such utilities (as necessary) in the
<filename>src/tools</filename> directory along with the port itself so
that it is available to future maintainers.</para>
<para>In the <filename>src/contrib/tcl</filename> level directory, a file
called <filename>FREEBSD-upgrade</filename> should be added and it
should states things like:</para>
<itemizedlist>
<listitem>
<para>Which files have been left out</para>
</listitem>
<listitem>
<para>Where the original distribution was obtained from and/or
the official master site.</para>
<para>Where the original distribution was obtained from and/or the
official master site.</para>
</listitem>
<listitem>
@ -170,18 +162,15 @@ MAINTAINER= email-addresses</programlisting>
</listitem>
<listitem>
<para>Perhaps an overview of the FreeBSD-specific changes that
have been made.</para>
<para>Perhaps an overview of the FreeBSD-specific changes that have
been made.</para>
</listitem>
</itemizedlist>
<para>However, please do not import
<filename>FREEBSD-upgrade</filename> with the contributed source.
Rather you should <command>cvs add FREEBSD-upgrade ; cvs ci</command> after the
initial import. Example wording from
<filename>src/contrib/cpio</filename> is below:</para>
<para>However, please do not import <filename>FREEBSD-upgrade</filename>
with the contributed source. Rather you should <command>cvs add
FREEBSD-upgrade ; cvs ci</command> after the initial import. Example
wording from <filename>src/contrib/cpio</filename> is below:</para>
<programlisting>
This directory contains virgin sources of the original distribution files
@ -222,78 +211,74 @@ All local changes should be submitted to "cpio@gnu.ai.mit.edu" for
inclusion in the next vendor release.
obrien@freebsd.org - 30 March 1997</programlisting>
</sect1>
<sect1 id="policies-shlib">
<title>Shared Libraries</title>
<para><emphasis>Contributed by &a.asami;, &a.peter;, and
&a.obrien;.<!-- <br> --> 9 December 1996.</emphasis></para>
<para><emphasis>Contributed by &a.asami;, &a.peter;, and &a.obrien;.<!--
<br> --> 9 December 1996.</emphasis></para>
<para>If you are adding shared library support to a port or other
piece of software that doesn't have one, the version numbers should
follow these rules. Generally, the resulting numbers will have
nothing to do with the release version of the software.</para>
<para>If you are adding shared library support to a port or other piece of
software that doesn't have one, the version numbers should follow these
rules. Generally, the resulting numbers will have nothing to do with
the release version of the software.</para>
<para>The three principles of shared library building are:</para>
<itemizedlist>
<listitem>
<para>Start from <literal>1.0</literal></para>
</listitem>
<listitem>
<para>If there is a change that is backwards compatible, bump
minor number</para>
</listitem>
<listitem>
<para>If there is an incompatible change, bump major
<para>If there is a change that is backwards compatible, bump minor
number</para>
</listitem>
<listitem>
<para>If there is an incompatible change, bump major number</para>
</listitem>
</itemizedlist>
<para>For instance, added functions and bugfixes result in the minor
version number being bumped, while deleted functions, changed
function call syntax etc. will force the major version number to
change.</para>
version number being bumped, while deleted functions, changed function
call syntax etc. will force the major version number to change.</para>
<para>Stick to version numbers of the form major.minor (<replaceable>x</replaceable>.<replaceable>y</replaceable>). Our
dynamic linker does not handle version numbers of the form <replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable>
well. Any version number after the <replaceable>y</replaceable> (ie. the third digit) is
totally ignored when comparing shared lib version numbers to decide
which library to link with. Given two shared libraries that differ
only in the &ldquo;micro&rdquo; revision, <command>ld.so</command> will link with the higher one.
Ie: if you link with <filename>libfoo.so.3.3.3</filename>, the
linker only records <literal>3.3</literal> in the headers, and will link with anything
starting with <replaceable>libfoo.so.3</replaceable>.<replaceable>(anything &gt;=
3)</replaceable>.<replaceable>(highest available)</replaceable>.</para>
<para>Stick to version numbers of the form major.minor
(<replaceable>x</replaceable>.<replaceable>y</replaceable>). Our
dynamic linker does not handle version numbers of the form
<replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable>
well. Any version number after the <replaceable>y</replaceable>
(ie. the third digit) is totally ignored when comparing shared lib
version numbers to decide which library to link with. Given two shared
libraries that differ only in the &ldquo;micro&rdquo; revision,
<command>ld.so</command> will link with the higher one. Ie: if you link
with <filename>libfoo.so.3.3.3</filename>, the linker only records
<literal>3.3</literal> in the headers, and will link with anything
starting with
<replaceable>libfoo.so.3</replaceable>.<replaceable>(anything &gt;=
3)</replaceable>.<replaceable>(highest
available)</replaceable>.</para>
<note>
<para><command>ld.so</command> will always use the highest
&ldquo;minor&rdquo; revision. Ie: it will use <filename>libc.so.2.2</filename>
in preference to <filename>libc.so.2.0</filename>, even if the
program was initially linked with
<filename>libc.so.2.0</filename>.</para>
&ldquo;minor&rdquo; revision. Ie: it will use
<filename>libc.so.2.2</filename> in preference to
<filename>libc.so.2.0</filename>, even if the program was initially
linked with <filename>libc.so.2.0</filename>.</para>
</note>
<para>For non-port libraries, it is also our policy to change the
shared library version number only once between releases. When you
make a change to a system library that requires the version number
to be bumped, check the <filename>Makefile</filename>'s commit logs.
It is the responsibility of the committer to ensure that the first
such change since the release will result in the shared library
version number in the <filename>Makefile</filename> to be updated,
and any subsequent changes will not.</para>
<para>For non-port libraries, it is also our policy to change the shared
library version number only once between releases. When you make a
change to a system library that requires the version number to be
bumped, check the <filename>Makefile</filename>'s commit logs. It is the
responsibility of the committer to ensure that the first such change
since the release will result in the shared library version number in
the <filename>Makefile</filename> to be updated, and any subsequent
changes will not.</para>
</sect1>
</chapter>
</chapter>
<!--
Local Variables:

835
en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
View file

File diff suppressed because it is too large Load diff

265
en_US.ISO8859-1/books/handbook/backups/chapter.sgml
View file

@ -9,10 +9,10 @@
impossible to provide a exhaustive listing of hardware that FreeBSD
supports, this section serves as a catalog of the device drivers included
with FreeBSD and the hardware each drivers supports. Where possible and
appropriate, notes about specific products are included. You may also want
to refer to <link linkend="kernelconfig-config"> the kernel configuration
file</link> section in this handbook for a list of supported
devices.</para>
appropriate, notes about specific products are included. You may also
want to refer to <link linkend="kernelconfig-config"> the kernel
configuration file</link> section in this handbook for a list of
supported devices.</para>
<para>As FreeBSD is a volunteer project without a funded testing department,
we depend on you, the user, for much of the information contained in this
@ -37,8 +37,7 @@
DLT.</para>
<sect2 id="backups-tapebackups-4mm">
<title>4mm (DDS: Digital Data
Storage)</title>
<title>4mm (DDS: Digital Data Storage)</title>
<para>4mm tapes are replacing QIC as the workstation backup media of
choice. This trend accelerated greatly when Conner purchased Archive,
@ -52,9 +51,9 @@
<para>Data thruput on these drives starts ~150kB/s, peaking at ~500kB/s.
Data capacity starts at 1.3 GB and ends at 2.0 GB. Hardware
compression, available with most of these drives, approximately
doubles the capacity. Multi-drive tape library units can have 6 drives
in a single cabinet with automatic tape changing. Library capacities
reach 240 GB.</para>
doubles the capacity. Multi-drive tape library units can have 6
drives in a single cabinet with automatic tape changing. Library
capacities reach 240 GB.</para>
<para>4mm drives, like 8mm drives, use helical-scan. All the benefits
and drawbacks of helical-scan apply to both 4mm and 8mm drives.</para>
@ -73,19 +72,19 @@
One downside of 8mm tape is relatively short head and tape life due to
the high rate of relative motion of the tape across the heads.</para>
<para>Data thruput ranges from ~250kB/s to ~500kB/s. Data sizes start at
300 MB and go up to 7 GB. Hardware compression, available with most of
these drives, approximately doubles the capacity. These drives are
available as single units or multi-drive tape libraries with 6 drives
and 120 tapes in a single cabinet. Tapes are changed automatically by
the unit. Library capacities reach 840+ GB.</para>
<para>Data thruput ranges from ~250kB/s to ~500kB/s. Data sizes start
at 300 MB and go up to 7 GB. Hardware compression, available with
most of these drives, approximately doubles the capacity. These
drives are available as single units or multi-drive tape libraries
with 6 drives and 120 tapes in a single cabinet. Tapes are changed
automatically by the unit. Library capacities reach 840+ GB.</para>
<para>Data is recorded onto the tape using helical-scan, the heads are
positioned at an angle to the media (approximately 6 degrees). The
tape wraps around 270 degrees of the spool that holds the heads. The
spool spins while the tape slides over the spool. The result is a high
density of data and closely packed tracks that angle across the tape
from one edge to the other.</para>
spool spins while the tape slides over the spool. The result is a
high density of data and closely packed tracks that angle across the
tape from one edge to the other.</para>
</sect2>
<sect2 id="backups-tapebackups-qic">
@ -100,21 +99,22 @@
<emphasis>most</emphasis> common tape drive. Every site has a QIC
drive of some density or another. Therein lies the rub, QIC has a
large number of densities on physically similar (sometimes identical)
tapes. QIC drives are not quiet. These drives audibly seek before they
begin to record data and are clearly audible whenever reading, writing
or seeking. QIC tapes measure (6 x 4 x 0.7 inches; 15.2 x 10.2 x 1.7
mm). <link linkend="backups-tapebackups-mini">Mini-cartridges</link>,
which also use 1/4" wide tape are discussed separately. Tape libraries
and changers are not available.</para>
tapes. QIC drives are not quiet. These drives audibly seek before
they begin to record data and are clearly audible whenever reading,
writing or seeking. QIC tapes measure (6 x 4 x 0.7 inches; 15.2 x
10.2 x 1.7 mm). <link
linkend="backups-tapebackups-mini">Mini-cartridges</link>, which
also use 1/4" wide tape are discussed separately. Tape libraries and
changers are not available.</para>
<para>Data thruput ranges from ~150kB/s to ~500kB/s. Data capacity
ranges from 40 MB to 15 GB. Hardware compression is available on many
of the newer QIC drives. QIC drives are less frequently installed;
they are being supplanted by DAT drives.</para>
<para>Data is recorded onto the tape in tracks. The tracks run along the
long axis of the tape media from one end to the other. The number of
tracks, and therefore the width of a track, varies with the tape's
<para>Data is recorded onto the tape in tracks. The tracks run along
the long axis of the tape media from one end to the other. The number
of tracks, and therefore the width of a track, varies with the tape's
capacity. Most if not all newer drives provide backward-compatibility
at least for reading (but often also for writing). QIC has a good
reputation regarding the safety of the data (the mechanics are simpler
@ -160,15 +160,13 @@
<sect2>
<title>Using a new tape for the first time</title>
<para>The first time that you try to read or write a new,
completely blank tape, the operation will fail. The console
messages should be similar to:</para>
<para>The first time that you try to read or write a new, completely
blank tape, the operation will fail. The console messages should be
similar to:</para>
<screen>st0(ncr1:4:0): NOT READY asc:4,1
st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
<para>The tape does not contain an Identifier Block (block number 0).
All QIC tape drives since the adoption of QIC-525 standard write an
Identifier Block to the tape. There are two solutions:</para>
@ -178,12 +176,11 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
<para>Use the front panel button to eject the tape.</para>
<para>Re-insert the tape and
&man.dump.8; data to the tape.</para>
<para>Re-insert the tape and &man.dump.8; data to the tape.</para>
<para>&man.dump.8; will report <literal>DUMP:
End of tape detected</literal> and the console will show:
<literal>HARDWARE FAILURE info:280 asc:80,96</literal></para>
<para>&man.dump.8; will report <literal>DUMP: End of tape
detected</literal> and the console will show: <literal>HARDWARE
FAILURE info:280 asc:80,96</literal></para>
<para>rewind the tape using: <command>mt rewind</command></para>
@ -203,84 +200,81 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
<sect2>
<title>Dump and Restore</title>
<para>&man.dump.8; and &man.restore.8; are the traditional Unix backup programs. They operate
on the drive as a collection of disk blocks, below the abstractions of
files, links and directories that are created by the filesystems.
&man.dump.8; backs up devices, entire filesystems, not parts of a
filesystem and not directory trees that span more than one filesystem,
using either soft links &man.ln.1; or mounting one filesystem onto another.
&man.dump.8; does not write files and directories to tape, but
rather writes the data blocks that are the building blocks of files
and directories. &man.dump.8; has quirks that remain from its early days in
Version 6 of ATT Unix (circa 1975). The default parameters are
suitable for 9-track tapes (6250 bpi), not the high-density media
available today (up to 62,182 ftpi). These defaults must be overridden
on the command line to utilize the capacity of current tape
drives.</para>
<para>&man.dump.8; and &man.restore.8; are the traditional Unix backup
programs. They operate on the drive as a collection of disk blocks,
below the abstractions of files, links and directories that are
created by the filesystems. &man.dump.8; backs up devices, entire
filesystems, not parts of a filesystem and not directory trees that
span more than one filesystem, using either soft links &man.ln.1; or
mounting one filesystem onto another. &man.dump.8; does not write
files and directories to tape, but rather writes the data blocks that
are the building blocks of files and directories. &man.dump.8; has
quirks that remain from its early days in Version 6 of ATT Unix (circa
1975). The default parameters are suitable for 9-track tapes (6250
bpi), not the high-density media available today (up to 62,182 ftpi).
These defaults must be overridden on the command line to utilize the
capacity of current tape drives.</para>
<para>&man.rdump.8; and &man.rrestore.8; backup data across the
network to a tape drive attached to another computer. Both programs
rely upon &man.rcmd.3; and &man.ruserok.3; to access the remote tape
drive. Therefore, the user performing the backup must have
<para>&man.rdump.8; and &man.rrestore.8; backup data across the network
to a tape drive attached to another computer. Both programs rely upon
&man.rcmd.3; and &man.ruserok.3; to access the remote tape drive.
Therefore, the user performing the backup must have
<literal>rhosts</literal> access to the remote computer. The
arguments to &man.rdump.8; and &man.rrestore.8; must suitable to use on the remote computer. (e.g.
When <command>rdump</command>'ing from a FreeBSD computer to an
Exabyte tape drive connected to a Sun called
<hostid>komodo</hostid>, use: <command>/sbin/rdump 0dsbfu 54000
13000 126 komodo:/dev/nrst8 /dev/rsd0a 2>&amp;1</command>) Beware:
there are security implications to allowing <literal>rhosts</literal>
arguments to &man.rdump.8; and &man.rrestore.8; must suitable to use
on the remote computer. (e.g. When <command>rdump</command>'ing from
a FreeBSD computer to an Exabyte tape drive connected to a Sun called
<hostid>komodo</hostid>, use: <command>/sbin/rdump 0dsbfu 54000 13000
126 komodo:/dev/nrst8 /dev/rsd0a 2>&amp;1</command>) Beware: there
are security implications to allowing <literal>rhosts</literal>
commands. Evaluate your situation carefully.</para>
</sect2>
<sect2>
<title>Tar</title>
<para>&man.tar.1; also dates back to Version 6 of ATT Unix (circa
1975). &man.tar.1; operates in cooperation with the filesystem;
&man.tar.1; writes files and directories to tape.
&man.tar.1; does not support the full range of options that are
available from &man.cpio.1;, but &man.tar.1; does not require the
unusual command pipeline that &man.cpio.1; uses.</para>
<para>&man.tar.1; also dates back to Version 6 of ATT Unix (circa 1975).
&man.tar.1; operates in cooperation with the filesystem; &man.tar.1;
writes files and directories to tape. &man.tar.1; does not support the
full range of options that are available from &man.cpio.1;, but
&man.tar.1; does not require the unusual command pipeline that
&man.cpio.1; uses.</para>
<para>Most versions of &man.tar.1; do not support backups across the network. The GNU
version of &man.tar.1;, which FreeBSD utilizes,
supports remote devices using the same syntax as
&man.rdump.8;. To &man.tar.1; to an Exabyte tape drive connected to a Sun called
<hostid>komodo</hostid>, use: <command>/usr/bin/tar cf komodo:/dev/nrst8 .
2>&amp;1</command>. For versions without remote device support,
you can use a pipeline and &man.rsh.1; to send the data to a
remote tape drive. (XXX add an example command)</para>
<para>Most versions of &man.tar.1; do not support backups across the
network. The GNU version of &man.tar.1;, which FreeBSD utilizes,
supports remote devices using the same syntax as &man.rdump.8;. To
&man.tar.1; to an Exabyte tape drive connected to a Sun called
<hostid>komodo</hostid>, use: <command>/usr/bin/tar cf
komodo:/dev/nrst8 . 2>&amp;1</command>. For versions without remote
device support, you can use a pipeline and &man.rsh.1; to send the
data to a remote tape drive. (XXX add an example command)</para>
</sect2>
<sect2>
<title>Cpio</title>
<para>&man.cpio.1; is the original Unix
file interchange tape program for magnetic media. &man.cpio.1; has options (among many
others) to perform byte-swapping, write a number of different
archives format, and pipe the data to other programs. This last
feature makes &man.cpio.1; and excellent choice for
installation media. &man.cpio.1; does not know how to walk
the directory tree and a list of files must be provided thru
<filename>STDIN</filename>.</para>
<para>&man.cpio.1; is the original Unix file interchange tape program
for magnetic media. &man.cpio.1; has options (among many others) to
perform byte-swapping, write a number of different archives format,
and pipe the data to other programs. This last feature makes
&man.cpio.1; and excellent choice for installation media.
&man.cpio.1; does not know how to walk the directory tree and a list
of files must be provided thru <filename>STDIN</filename>.</para>
<para>&man.cpio.1; does not support backups
across the network. You can use a pipeline and &man.rsh.1; to send the data to a
remote tape drive. (XXX add an example command)</para>
<para>&man.cpio.1; does not support backups across the network. You can
use a pipeline and &man.rsh.1; to send the data to a remote tape
drive. (XXX add an example command)</para>
</sect2>
<sect2>
<title>Pax</title>
<para>&man.pax.1; is IEEE/POSIX's answer to
&man.tar.1; and &man.cpio.1;. Over the years the
various versions of &man.tar.1; and &man.cpio.1;
have gotten slightly incompatible. So rather than fight it out to
fully standardize them, POSIX created a new archive utility.
&man.pax.1; attempts to read and write many of the various
&man.cpio.1; and &man.tar.1; formats, plus new formats of its own. Its command set
more resembles &man.cpio.1; than
&man.tar.1;.</para>
<para>&man.pax.1; is IEEE/POSIX's answer to &man.tar.1; and
&man.cpio.1;. Over the years the various versions of &man.tar.1;
and &man.cpio.1; have gotten slightly incompatible. So rather than
fight it out to fully standardize them, POSIX created a new archive
utility. &man.pax.1; attempts to read and write many of the various
&man.cpio.1; and &man.tar.1; formats, plus new formats of its own.
Its command set more resembles &man.cpio.1; than &man.tar.1;.</para>
</sect2>
<sect2 id="backups-programs-amanda">
@ -290,9 +284,9 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
(Advanced Maryland Network Disk Archiver) is a client/server backup
system, rather than a single program. An Amanda server will backup to
a single tape drive any number of computers that have Amanda clients
and network communications with the Amanda server. A common problem at
locations with a number of large disks is the length of time required
to backup to data directly to tape exceeds the amount of time
and network communications with the Amanda server. A common problem
at locations with a number of large disks is the length of time
required to backup to data directly to tape exceeds the amount of time
available for the task. Amanda solves this problem. Amanda can use a
"holding disk" to backup several filesystems at the same time. Amanda
creates "archive sets": a group of tapes used over a period of time to
@ -312,9 +306,9 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
<title>Do nothing</title>
<para>&ldquo;Do nothing&rdquo; is not a computer program, but it is the
most widely used backup strategy. There are no initial costs. There is
no backup schedule to follow. Just say no. If something happens to
your data, grin and bear it!</para>
most widely used backup strategy. There are no initial costs. There
is no backup schedule to follow. Just say no. If something happens
to your data, grin and bear it!</para>
<para>If your time and your data is worth little to nothing, then
&ldquo;Do nothing&rdquo; is the most suitable backup program for your
@ -334,19 +328,20 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
<sect2>
<title>Which Backup Program is Best?</title>
<para>&man.dump.8; <emphasis>Period.</emphasis>
Elizabeth D. Zwicky torture tested all the backup programs discussed
here. The clear choice for preserving all your data and all the
peculiarities of Unix filesystems is &man.dump.8;. Elizabeth created
filesystems containing a large variety of unusual conditions (and some
not so unusual ones) and tested each program by do a backup and
restore of that filesystems. The peculiarities included: files with
holes, files with holes and a block of nulls, files with funny
characters in their names, unreadable and unwritable files, devices,
files that change size during the backup, files that are
created/deleted during the backup and more. She presented the results
at LISA V in Oct. 1991. See <ulink
url="http://reality.sgi.com/zwicky_neu/testdump.doc.html">torture-testing Backup and Archive Programs</ulink>.</para>
<para>&man.dump.8; <emphasis>Period.</emphasis> Elizabeth D. Zwicky
torture tested all the backup programs discussed here. The clear
choice for preserving all your data and all the peculiarities of Unix
filesystems is &man.dump.8;. Elizabeth created filesystems containing
a large variety of unusual conditions (and some not so unusual ones)
and tested each program by do a backup and restore of that
filesystems. The peculiarities included: files with holes, files with
holes and a block of nulls, files with funny characters in their
names, unreadable and unwritable files, devices, files that change
size during the backup, files that are created/deleted during the
backup and more. She presented the results at LISA V in Oct. 1991.
See <ulink
url="http://reality.sgi.com/zwicky_neu/testdump.doc.html">torture-testing
Backup and Archive Programs</ulink>.</para>
</sect2>
<sect2>
@ -370,12 +365,12 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
messages. If all your devices are listed and functional, skip on to
step three.</para>
<para>Otherwise, you have to create two custom bootable floppies
which has a kernel that can mount your all of your disks and
access your tape drive. These floppies must contain:
&man.fdisk.8;, &man.disklabel.8;, &man.newfs.8;, &man.mount.8;, and whichever backup
program you use. These programs must be statically linked. If you
use &man.dump.8;, the floppy must contain
<para>Otherwise, you have to create two custom bootable floppies which
has a kernel that can mount your all of your disks and access your
tape drive. These floppies must contain:
&man.fdisk.8;, &man.disklabel.8;, &man.newfs.8;, &man.mount.8;, and
whichever backup program you use. These programs must be statically
linked. If you use &man.dump.8;, the floppy must contain
&man.restore.8;.</para>
<para>Third, create backup tapes regularly. Any changes that you make
@ -385,19 +380,19 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
<para>Fourth, test the floppies (either <filename>boot.flp</filename>
and <filename>fixit.flp</filename> or the two custom bootable
floppies you made in step two.) and backup tapes. Make notes of the
procedure. Store these notes with the bootable floppy, the printouts
and the backup tapes. You will be so distraught when restoring that
the notes may prevent you from destroying your backup tapes (How?
In place of <command>tar xvf /dev/rst0</command>, you might
accidently type <command>tar cvf /dev/rst0</command> and over-write
your backup tape).</para>
procedure. Store these notes with the bootable floppy, the
printouts and the backup tapes. You will be so distraught when
restoring that the notes may prevent you from destroying your backup
tapes (How? In place of <command>tar xvf /dev/rst0</command>, you
might accidently type <command>tar cvf /dev/rst0</command> and
over-write your backup tape).</para>
<para>For an added measure of security, make bootable floppies and two
backup tapes each time. Store one of each at a remote location. A
remote location is NOT the basement of the same office building. A
number of firms in the World Trade Center learned this lesson the
hard way. A remote location should be physically separated from your
computers and disk drives by a significant distance.</para>
hard way. A remote location should be physically separated from
your computers and disk drives by a significant distance.</para>
<para>An example script for creating a bootable floppy:</para>
@ -586,13 +581,13 @@ chmod 644 /mnt/etc/passwd
/mnt</command>) the root partition of your first disk. If the
disklabel was damaged, use &man.disklabel.8; to re-partition and
label the disk to match the label that your printed and saved. Use
&man.newfs.8; to re-create the
filesystems. Re-mount the root partition of the floppy read-write
(<command>mount -u -o rw /mnt</command>). Use your backup program
and backup tapes to recover the data for this filesystem (e.g.
<command>restore vrf /dev/st0</command>). Unmount the filesystem
(e.g. <command>umount /mnt</command>) Repeat for each filesystem
that was damaged.</para>
&man.newfs.8; to re-create the filesystems. Re-mount the root
partition of the floppy read-write (<command>mount -u -o rw
/mnt</command>). Use your backup program and backup tapes to
recover the data for this filesystem (e.g. <command>restore vrf
/dev/st0</command>). Unmount the filesystem (e.g. <command>umount
/mnt</command>) Repeat for each filesystem that was
damaged.</para>
<para>Once your system is running, backup your data onto new tapes.
Whatever caused the crash or data loss may strike again. An another

89
en_US.ISO8859-1/books/handbook/basics/chapter.sgml
View file

@ -1,33 +1,27 @@
<chapter id="basics">
<chapter id="basics">
<title>Unix Basics</title>
<sect1 id="basics-man">
<title>The Online Manual</title>
<para>The most comprehensive documentation on FreeBSD is in the form
of <emphasis>man pages</emphasis>. Nearly every program on the
system comes with a short reference manual explaining the basic
operation and various arguments. These manuals can be view with the
<command>man</command>
command. Use of the <command>man</command> command is simple:</para>
<para>The most comprehensive documentation on FreeBSD is in the form of
<emphasis>man pages</emphasis>. Nearly every program on the system
comes with a short reference manual explaining the basic operation and
various arguments. These manuals can be view with the
<command>man</command> command. Use of the <command>man</command>
command is simple:</para>
<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>
<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput>
</screen>
<para><replaceable>command</replaceable> is
the name of the command you wish to learn about. For example, to
learn more about <command>ls</command> command type:</para>
<para><replaceable>command</replaceable> is the name of the command you
wish to learn about. For example, to learn more about
<command>ls</command> command type:</para>
<screen>&prompt.user; <userinput>man ls</userinput></screen>
<para>The online manual is divided up into numbered sections:</para>
<orderedlist>
<listitem>
<para>User commands</para>
</listitem>
@ -59,57 +53,47 @@
<listitem>
<para>System maintenance and operation commands</para>
</listitem>
</orderedlist>
<para>In some cases, the same topic may appear in more than
one section of the on-line manual. For example, there is a
<command>chmod</command>
user command and a <function>chmod()</function> system call. In
this case, you can tell the <command>man</command> command which one you want by
specifying the section:</para>
<para>In some cases, the same topic may appear in more than one section of
the on-line manual. For example, there is a <command>chmod</command>
user command and a <function>chmod()</function> system call. In this
case, you can tell the <command>man</command> command which one you want
by specifying the section:</para>
<screen>&prompt.user; <userinput>man 1 chmod</userinput></screen>
<para>This will display the manual page for the user
command <command>chmod</command>. References to a
particular section of the on-line manual are traditionally placed in
parenthesis in written documentation, so &man.chmod.1; refers to the
<command>chmod</command>
user command and &man.chmod.2; refers to the
<para>This will display the manual page for the user command
<command>chmod</command>. References to a particular section of the
on-line manual are traditionally placed in parenthesis in written
documentation, so &man.chmod.1; refers to the
<command>chmod</command> user command and &man.chmod.2; refers to the
system call.</para>
<para>This is fine if you know the name of the command and simply wish
to know how to use it, but what if you cannot recall the command
name? You can use <command>man</command> to search for keywords in the
command <emphasis>descriptions</emphasis> by using the
<option>-k</option> switch:</para>
<para>This is fine if you know the name of the command and simply wish to
know how to use it, but what if you cannot recall the command name? You
can use <command>man</command> to search for keywords in the command
<emphasis>descriptions</emphasis> by using the <option>-k</option>
switch:</para>
<screen>&prompt.user; <userinput>man -k mail</userinput></screen>
<para>With this command you will be presented with a
list of commands that have the keyword &ldquo;mail&rdquo; in their descriptions.
This is actually functionally equivalent to using the <command>apropos</command>
<para>With this command you will be presented with a list of commands that
have the keyword &ldquo;mail&rdquo; in their descriptions. This is
actually functionally equivalent to using the <command>apropos</command>
command.</para>
<para>So, you are looking at all those fancy commands in
<filename>/usr/bin</filename> but do not even have the faintest idea
what most of them actually do? Simply do a
<screen>&prompt.user; <userinput>cd /usr/bin; man -f *</userinput></screen>
or
<screen>&prompt.user; <userinput>cd /usr/bin; whatis *</userinput></screen>
which does the same thing.</para>
which does the same thing.</para>
</sect1>
<sect1 id="basics-info">
@ -120,20 +104,17 @@
programs come with more extensive hypertext documents called
&ldquo;info&rdquo; files which can be viewed with the
<command>info</command> command or, if you installed
<command>emacs</command>, the info mode of <command>emacs</command>.</para>
<command>emacs</command>, the info mode of
<command>emacs</command>.</para>
<para>To use the &man.info.1; command, simply type:</para>
<screen>&prompt.user; <userinput>info</userinput></screen>
<para>For a brief introduction, type <userinput>h</userinput>. For a quick
command reference, type <userinput>?</userinput>.</para>
<para>For a brief introduction, type <userinput>h</userinput>. For a
quick command reference, type <userinput>?</userinput>.</para>
</sect1>
</chapter>
</chapter>
<!--
Local Variables:

357
en_US.ISO8859-1/books/handbook/bibliography/chapter.sgml
View file

@ -1,13 +1,11 @@
<chapter id="bibliography">
<chapter id="bibliography">
<title>Bibliography</title>
<para>While the manual pages provide the definitive reference for
individual pieces of the FreeBSD operating system, they are notorious
for not illustrating how to put the pieces together to make the whole
operating system run smoothly. For this, there is no substitute for a
good book on UNIX system administration and a good users'
manual.</para>
<para>While the manual pages provide the definitive reference for individual
pieces of the FreeBSD operating system, they are notorious for not
illustrating how to put the pieces together to make the whole operating
system run smoothly. For this, there is no substitute for a good book on
UNIX system administration and a good users' manual.</para>
<sect1>
<title>Books &amp; Magazines Specific to FreeBSD</title>
@ -15,9 +13,7 @@
<para><emphasis>International books &amp;
Magazines:</emphasis></para>
<itemizedlist>
<listitem>
<para><ulink
URL="http://freebsd.csie.nctu.edu.tw/~jdli/book.html">Using
@ -25,13 +21,13 @@
</listitem>
<listitem>
<para>FreeBSD for PC 98'ers (in Japanese), published by SHUWA
System Co, LTD. ISBN 4-87966-468-5 C3055 P2900E.</para>
<para>FreeBSD for PC 98'ers (in Japanese), published by SHUWA System
Co, LTD. ISBN 4-87966-468-5 C3055 P2900E.</para>
</listitem>
<listitem>
<para>FreeBSD (in Japanese), published by CUTT. ISBN
4-906391-22-2 C3055 P2400E.</para>
<para>FreeBSD (in Japanese), published by CUTT. ISBN 4-906391-22-2
C3055 P2400E.</para>
</listitem>
<listitem>
@ -45,9 +41,9 @@
</listitem>
<listitem>
<para>FreeBSD Handbook (Japanese translation), published by
<ulink URL="http://www.ascii.co.jp/">ASCII</ulink>. ISBN
4-7561-1580-2 P3800E.</para>
<para>FreeBSD Handbook (Japanese translation), published by <ulink
URL="http://www.ascii.co.jp/">ASCII</ulink>. ISBN 4-7561-1580-2
P3800E.</para>
</listitem>
<listitem>
@ -56,179 +52,157 @@
</listitem>
<listitem>
<para><ulink url="http://www.pc.mycom.co.uk/FreeBSD/install-manual.html">FreeBSD
Install and Utilization Manual</ulink> (in Japanese),
published by <ulink url="http://www.pc.mycom.co.jp/">Mainichi
Communications Inc.</ulink>.</para>
<para><ulink
url="http://www.pc.mycom.co.uk/FreeBSD/install-manual.html">FreeBSD Install and Utilization Manual</ulink> (in Japanese), published by <ulink url="http://www.pc.mycom.co.jp/">Mainichi Communications Inc.</ulink>.</para>
</listitem>
</itemizedlist>
<para><emphasis>English language books &amp;
Magazines:</emphasis></para>
<para><emphasis>English language books &amp; Magazines:</emphasis></para>
<itemizedlist>
<listitem>
<para><ulink
URL="http://www.cdrom.com/titles/freebsd/bsdbook2.htm">The
Complete FreeBSD</ulink>, published by <ulink
URL="http://www.cdrom.com">Walnut Creek
CDROM</ulink>.</para>
URL="http://www.cdrom.com">Walnut Creek CDROM</ulink>.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>Users' Guides</title>
<itemizedlist>
<listitem>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD User's Reference Manual</emphasis>. O'Reilly
&amp; Associates, Inc., 1994.<!-- <br> --> ISBN
1-56592-075-9</para>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD
User's Reference Manual</emphasis>. O'Reilly &amp; Associates,
Inc., 1994.<!-- <br> --> ISBN 1-56592-075-9</para>
</listitem>
<listitem>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD User's Supplementary Documents</emphasis>.
O'Reilly &amp; Associates, Inc., 1994.<!-- <br> --> ISBN
1-56592-076-7</para>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD
User's Supplementary Documents</emphasis>. O'Reilly &amp;
Associates, Inc., 1994.<!-- <br> --> ISBN 1-56592-076-7</para>
</listitem>
<listitem>
<para><emphasis>UNIX in a Nutshell</emphasis>. O'Reilly
&amp; Associates, Inc., 1990.<!-- <br> --> ISBN
093717520X</para>
<para><emphasis>UNIX in a Nutshell</emphasis>. O'Reilly &amp;
Associates, Inc., 1990.<!-- <br> --> ISBN 093717520X</para>
</listitem>
<listitem>
<para>Mui, Linda. <emphasis>What You Need To Know When You Can't
Find Your UNIX System Administrator</emphasis>. O'Reilly
&amp; Associates, Inc., 1995. <!-- <br> --> ISBN 1-56592-104-6</para>
<para>Mui, Linda. <emphasis>What You Need To Know When You Can't Find
Your UNIX System Administrator</emphasis>. O'Reilly &amp;
Associates, Inc., 1995. <!-- <br> --> ISBN 1-56592-104-6</para>
</listitem>
<listitem>
<para><ulink URL="http://www-wks.acs.ohio-state.edu/">Ohio State
University</ulink> has written a <ulink
URL="http://www-wks.acs.ohio-state.edu/unix_course/unix.html">UNIX Introductory Course</ulink> which is available online in HTML and postscript format.</para>
URL="http://www-wks.acs.ohio-state.edu/unix_course/unix.html">UNIX
Introductory Course</ulink> which is available online in HTML and
postscript format.</para>
</listitem>
<listitem>
<para><ulink url="http://www.jp.FreeBSD.ORG/">Jpman Project,
Japan FreeBSD Users Group</ulink>. <ulink
url="http://www.pc.mycom.co.jp/FreeBSD/urm.html">FreeBSD
User's Reference Manual</ulink> (Japanese translation).
<ulink url="http://www.pc.mycom.co.jp/">Mainichi
Communications Inc.</ulink>, 1998. ISBN4-8399-0088-4
P3800E.</para>
<para><ulink url="http://www.jp.FreeBSD.ORG/">Jpman Project, Japan
FreeBSD Users Group</ulink>. <ulink
url="http://www.pc.mycom.co.jp/FreeBSD/urm.html">FreeBSD User's
Reference Manual</ulink> (Japanese translation). <ulink
url="http://www.pc.mycom.co.jp/">Mainichi Communications
Inc.</ulink>, 1998. ISBN4-8399-0088-4 P3800E.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>Administrators' Guides</title>
<itemizedlist>
<listitem>
<para>Albitz, Paul and Liu, Cricket. <emphasis>DNS and
BIND</emphasis>, 2nd Ed. O'Reilly &amp; Associates, Inc.,
1997. <!-- <br> --> ISBN 1-56592-236-0</para>
BIND</emphasis>, 2nd Ed. O'Reilly &amp; Associates, Inc., 1997.
<!-- <br> --> ISBN 1-56592-236-0</para>
</listitem>
<listitem>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD System Manager's Manual</emphasis>. O'Reilly
&amp; Associates, Inc., 1994. <!-- <br> --> ISBN
1-56592-080-5</para>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD
System Manager's Manual</emphasis>. O'Reilly &amp; Associates,
Inc., 1994. <!-- <br> --> ISBN 1-56592-080-5</para>
</listitem>
<listitem>
<para>Costales, Brian, et al. <emphasis>Sendmail</emphasis>, 2nd
Ed. O'Reilly &amp; Associates, Inc., 1997.<!-- <br> --> ISBN
<para>Costales, Brian, et al. <emphasis>Sendmail</emphasis>, 2nd Ed.
O'Reilly &amp; Associates, Inc., 1997.<!-- <br> --> ISBN
1-56592-222-0</para>
</listitem>
<listitem>
<para>Frisch, &AElig;leen. <emphasis>Essential System
Administration</emphasis>, 2nd Ed. O'Reilly &amp;
Associates, Inc., 1995. <!-- <br> -->ISBN 1-56592-127-5</para>
Administration</emphasis>, 2nd Ed. O'Reilly &amp; Associates,
Inc., 1995. <!-- <br> -->ISBN 1-56592-127-5</para>
</listitem>
<listitem>
<para>Hunt, Craig. <emphasis>TCP/IP Network
Administration</emphasis>. O'Reilly &amp; Associates, Inc.,
1992. <!-- <br> --> ISBN 0-937175-82-X</para>
Administration</emphasis>. O'Reilly &amp; Associates, Inc., 1992.
<!-- <br> --> ISBN 0-937175-82-X</para>
</listitem>
<listitem>
<para>Nemeth, Evi. <emphasis>UNIX System Administration
Handbook</emphasis>. 2nd Ed. Prentice Hall, 1995. <!-- <br>
--> ISBN 0131510517</para>
Handbook</emphasis>. 2nd Ed. Prentice Hall, 1995. <!-- <br> -->
ISBN 0131510517</para>
</listitem>
<listitem>
<para>Stern, Hal <emphasis>Managing NFS and NIS</emphasis>
O'Reilly &amp; Associates, Inc., 1991. <!-- <br> --> ISBN
<para>Stern, Hal <emphasis>Managing NFS and NIS</emphasis> O'Reilly
&amp; Associates, Inc., 1991. <!-- <br> --> ISBN
0-937175-75-7</para>
</listitem>
<listitem>
<para><ulink url="http://www.jp.FreeBSD.ORG/">Jpman Project,
Japan FreeBSD Users Group</ulink>. <ulink
url="http://www.pc.mycom.co.jp/FreeBSD/sam.html">FreeBSD
System Administrator's Manual</ulink> (Japanese translation).
<ulink url="http://www.pc.mycom.co.jp/">Mainichi
Communications Inc.</ulink>, 1998. ISBN4-8399-0109-0
P3300E.</para>
<para><ulink url="http://www.jp.FreeBSD.ORG/">Jpman Project, Japan
FreeBSD Users Group</ulink>. <ulink
url="http://www.pc.mycom.co.jp/FreeBSD/sam.html">FreeBSD System
Administrator's Manual</ulink> (Japanese translation). <ulink
url="http://www.pc.mycom.co.jp/">Mainichi Communications
Inc.</ulink>, 1998. ISBN4-8399-0109-0 P3300E.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>Programmers' Guides</title>
<itemizedlist>
<listitem>
<para>Asente, Paul. <emphasis>X Window System
Toolkit</emphasis>. Digital Press. <!-- <br> --> ISBN
1-55558-051-3</para>
<para>Asente, Paul. <emphasis>X Window System Toolkit</emphasis>.
Digital Press. <!-- <br> --> ISBN 1-55558-051-3</para>
</listitem>
<listitem>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD Programmer's Reference Manual</emphasis>.
O'Reilly &amp; Associates, Inc., 1994. <!-- <br> --> ISBN
1-56592-078-3</para>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD
Programmer's Reference Manual</emphasis>. O'Reilly &amp;
Associates, Inc., 1994. <!-- <br> --> ISBN 1-56592-078-3</para>
</listitem>
<listitem>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD Programmer's Supplementary
Documents</emphasis>. O'Reilly &amp; Associates, Inc., 1994.
<!-- <br> --> ISBN 1-56592-079-1</para>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD
Programmer's Supplementary Documents</emphasis>. O'Reilly &amp;
Associates, Inc., 1994. <!-- <br> --> ISBN 1-56592-079-1</para>
</listitem>
<listitem>
<para>Harbison, Samuel P. and Steele, Guy L. Jr. <emphasis>C: A
Reference Manual</emphasis>. 4rd ed. Prentice Hall, 1995.
<!-- <br> -->ISBN 0-13-326224-3</para>
Reference Manual</emphasis>. 4rd ed. Prentice Hall, 1995. <!--
<br> -->ISBN 0-13-326224-3</para>
</listitem>
<listitem>
<para>Kernighan, Brian and Dennis M. Ritchie. <emphasis>The C
Programming Language.</emphasis>. PTR Prentice Hall, 1988.
<!-- <br> --> ISBN 0-13-110362-9</para>
Programming Language.</emphasis>. PTR Prentice Hall, 1988. <!--
<br> --> ISBN 0-13-110362-9</para>
</listitem>
<listitem>
@ -238,15 +212,14 @@
</listitem>
<listitem>
<para>Plauger, P. J. <emphasis>The Standard C
Library</emphasis>. Prentice Hall, 1992. <!-- <br> --> ISBN
0-13-131509-9</para>
<para>Plauger, P. J. <emphasis>The Standard C Library</emphasis>.
Prentice Hall, 1992. <!-- <br> --> ISBN 0-13-131509-9</para>
</listitem>
<listitem>
<para>Stevens, W. Richard. <emphasis>Advanced Programming in the
UNIX Environment</emphasis>. Reading, Mass. :
Addison-Wesley, 1992<!-- <br> --> ISBN 0-201-56317-7</para>
<para>Stevens, W. Richard. <emphasis>Advanced Programming in the UNIX
Environment</emphasis>. Reading, Mass. : Addison-Wesley, 1992<!--
<br> --> ISBN 0-201-56317-7</para>
</listitem>
<listitem>
@ -257,72 +230,66 @@
<listitem>
<para>Wells, Bill. &ldquo;Writing Serial Drivers for UNIX&rdquo;.
<emphasis>Dr. Dobb's Journal</emphasis>. 19(15), December
1994. pp68-71, 97-99.</para>
<emphasis>Dr. Dobb's Journal</emphasis>. 19(15), December 1994.
pp68-71, 97-99.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>Operating System Internals</title>
<itemizedlist>
<listitem>
<para>Andleigh, Prabhat K. <emphasis>UNIX System
Architecture</emphasis>. Prentice-Hall, Inc., 1990.<!-- <br>
--> ISBN 0-13-949843-5</para>
Architecture</emphasis>. Prentice-Hall, Inc., 1990.<!-- <br> -->
ISBN 0-13-949843-5</para>
</listitem>
<listitem>
<para>Jolitz, William. &ldquo;Porting UNIX to the
386&rdquo;. <emphasis>Dr.
Dobb's Journal</emphasis>. January 1991-July 1992.</para>
<para>Jolitz, William. &ldquo;Porting UNIX to the 386&rdquo;.
<emphasis>Dr. Dobb's Journal</emphasis>. January 1991-July
1992.</para>
</listitem>
<listitem>
<para>Leffler, Samuel J., Marshall Kirk McKusick, Michael J
Karels and John Quarterman <emphasis>The Design and
Implementation of the 4.3BSD UNIX Operating
System</emphasis>. Reading, Mass. : Addison-Wesley,
1989.<!-- <br> --> ISBN 0-201-06196-1</para>
<para>Leffler, Samuel J., Marshall Kirk McKusick, Michael J Karels and
John Quarterman <emphasis>The Design and Implementation of the
4.3BSD UNIX Operating System</emphasis>. Reading, Mass. :
Addison-Wesley, 1989.<!-- <br> --> ISBN 0-201-06196-1</para>
</listitem>
<listitem>
<para>Leffler, Samuel J., Marshall Kirk McKusick, <emphasis>The
Design and Implementation of the 4.3BSD UNIX Operating
System: Answer Book</emphasis>. Reading, Mass. :
Addison-Wesley, 1991.<!-- <br> --> ISBN 0-201-54629-9</para>
<para>Leffler, Samuel J., Marshall Kirk McKusick, <emphasis>The Design
and Implementation of the 4.3BSD UNIX Operating System: Answer
Book</emphasis>. Reading, Mass. : Addison-Wesley, 1991.<!-- <br>
--> ISBN 0-201-54629-9</para>
</listitem>
<listitem>
<para>McKusick, Marshall Kirk, Keith Bostic, Michael J Karels,
and John Quarterman. <emphasis>The Design and Implementation
of the 4.4BSD Operating System</emphasis>. Reading, Mass. :
<para>McKusick, Marshall Kirk, Keith Bostic, Michael J Karels, and
John Quarterman. <emphasis>The Design and Implementation of the
4.4BSD Operating System</emphasis>. Reading, Mass. :
Addison-Wesley, 1996.<!-- <br> --> ISBN 0-201-54979-4</para>
</listitem>
<listitem>
<para>Stevens, W. Richard. <emphasis>TCP/IP Illustrated, Volume
1: The Protocols</emphasis>. Reading, Mass. :
Addison-Wesley, 1996.<!-- <br> --> ISBN 0-201-63346-9</para>
<para>Stevens, W. Richard. <emphasis>TCP/IP Illustrated, Volume 1:
The Protocols</emphasis>. Reading, Mass. : Addison-Wesley,
1996.<!-- <br> --> ISBN 0-201-63346-9</para>
</listitem>
<listitem>
<para>Schimmel, Curt. <emphasis>Unix Systems for Modern
Architectures</emphasis>. Reading, Mass. : Addison-Wesley,
1994. ISBN 0-201-63338-8</para>
Architectures</emphasis>. Reading, Mass. : Addison-Wesley, 1994.
ISBN 0-201-63338-8</para>
</listitem>
<listitem>
<para>Stevens, W. Richard. <emphasis>TCP/IP Illustrated, Volume
3: TCP for Transactions, HTTP, NNTP and the UNIX Domain
Protocols</emphasis>. Reading, Mass. : Addison-Wesley,
1996.<!-- <br> --> ISBN 0-201-63495-3</para>
<para>Stevens, W. Richard. <emphasis>TCP/IP Illustrated, Volume 3:
TCP for Transactions, HTTP, NNTP and the UNIX Domain
Protocols</emphasis>. Reading, Mass. : Addison-Wesley, 1996.<!--
<br> --> ISBN 0-201-63495-3</para>
</listitem>
<listitem>
@ -333,52 +300,41 @@
<listitem>
<para>Wright, Gary R. and W. Richard Stevens. <emphasis>TCP/IP
Illustrated, Volume 2: The Implementation</emphasis>.
Reading, Mass. : Addison-Wesley, 1995.<!-- <br> --> ISBN
0-201-63354-X</para>
Illustrated, Volume 2: The Implementation</emphasis>. Reading,
Mass. : Addison-Wesley, 1995.<!-- <br> --> ISBN 0-201-63354-X</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>Security Reference</title>
<itemizedlist>
<listitem>
<para>Cheswick, William R. and Steven M. Bellovin.
<emphasis>Firewalls and Internet Security: Repelling the Wily
Hacker</emphasis>. Reading, Mass. : Addison-Wesley,
1995.<!-- <br> --> ISBN 0-201-63357-4</para>
<para>Cheswick, William R. and Steven M. Bellovin. <emphasis>Firewalls
and Internet Security: Repelling the Wily Hacker</emphasis>.
Reading, Mass. : Addison-Wesley, 1995.<!-- <br> --> ISBN
0-201-63357-4</para>
</listitem>
<listitem>
<para>Garfinkel, Simson and Gene Spafford. <emphasis>Practical
UNIX Security</emphasis>. 2nd Ed. O'Reilly &amp; Associates,
Inc., 1996. <!-- <br> --> ISBN 1-56592-148-8</para>
<para>Garfinkel, Simson and Gene Spafford. <emphasis>Practical UNIX
Security</emphasis>. 2nd Ed. O'Reilly &amp; Associates, Inc.,
1996. <!-- <br> --> ISBN 1-56592-148-8</para>
</listitem>
<listitem>
<para>Garfinkel, Simson. <emphasis>PGP Pretty Good
Privacy</emphasis> O'Reilly &amp; Associates, Inc., 1995.
<!-- <br> --> ISBN 1-56592-098-8</para>
Privacy</emphasis> O'Reilly &amp; Associates, Inc., 1995. <!--
<br> --> ISBN 1-56592-098-8</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>Hardware Reference</title>
<itemizedlist>
<listitem>
<para>Anderson, Don and Tom Shanley. <emphasis>Pentium Processor
System Architecture</emphasis>. 2nd Ed. Reading, Mass. :
@ -386,10 +342,9 @@
</listitem>
<listitem>
<para>Ferraro, Richard F. <emphasis>Programmer's Guide to the
EGA, VGA, and Super VGA Cards</emphasis>. 3rd ed. Reading,
Mass. : Addison-Wesley, 1995.<!-- <br> --> ISBN
0-201-62490-7</para>
<para>Ferraro, Richard F. <emphasis>Programmer's Guide to the EGA,
VGA, and Super VGA Cards</emphasis>. 3rd ed. Reading, Mass. :
Addison-Wesley, 1995.<!-- <br> --> ISBN 0-201-62490-7</para>
</listitem>
<listitem>
@ -400,48 +355,43 @@
</listitem>
<listitem>
<para>Shanley, Tom. <emphasis>80486 System
Architecture</emphasis>. 3rd ed. Reading, Mass. :
Addison-Wesley, 1995. <!-- <br> -->ISBN 0-201-40994-1</para>
<para>Shanley, Tom. <emphasis>80486 System Architecture</emphasis>.
3rd ed. Reading, Mass. : Addison-Wesley, 1995. <!-- <br> -->ISBN
0-201-40994-1</para>
</listitem>
<listitem>
<para>Shanley, Tom. <emphasis>ISA System
Architecture</emphasis>. 3rd ed. Reading, Mass. :
Addison-Wesley, 1995.<!-- <br> --> ISBN 0-201-40996-8</para>
<para>Shanley, Tom. <emphasis>ISA System Architecture</emphasis>.
3rd ed. Reading, Mass. : Addison-Wesley, 1995.<!-- <br> --> ISBN
0-201-40996-8</para>
</listitem>
<listitem>
<para>Shanley, Tom. <emphasis>PCI System
Architecture</emphasis>. 3rd ed. Reading, Mass. :
Addison-Wesley, 1995. <!-- <br> -->ISBN 0-201-40993-3</para>
<para>Shanley, Tom. <emphasis>PCI System Architecture</emphasis>.
3rd ed. Reading, Mass. : Addison-Wesley, 1995. <!-- <br> -->ISBN
0-201-40993-3</para>
</listitem>
<listitem>
<para>Van Gilluwe, Frank. <emphasis>The Undocumented
PC</emphasis>. Reading, Mass: Addison-Wesley Pub. Co.,
1994.<!-- <br> --> ISBN 0-201-62277-7</para>
<para>Van Gilluwe, Frank. <emphasis>The Undocumented PC</emphasis>.
Reading, Mass: Addison-Wesley Pub. Co., 1994.<!-- <br> --> ISBN
0-201-62277-7</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>UNIX History</title>
<itemizedlist>
<listitem>
<para>Lion, John <emphasis>Lion's Commentary on UNIX, 6th Ed.
With Source Code</emphasis>. ITP Media Group, 1996.<!-- <br>
--> ISBN 1573980137</para>
<para>Lion, John <emphasis>Lion's Commentary on UNIX, 6th Ed. With
Source Code</emphasis>. ITP Media Group, 1996.<!-- <br> --> ISBN
1573980137</para>
</listitem>
<listitem>
<para>Raymond, Eric s. <emphasis>The New Hacker's Dictonary, 3rd
<para>Raymond, Eric S. <emphasis>The New Hacker's Dictonary, 3rd
edition</emphasis>. MIT Press, 1996.<!-- <br> --> ISBN
0-262-68092-0<!-- <br> --> Also known as the <ulink
URL="http://www.ccil.org/jargon/jargon.html">Jargon
@ -449,32 +399,32 @@
</listitem>
<listitem>
<para>Salus, Peter H. <emphasis>A quarter century of
UNIX</emphasis>. Addison-Wesley Publishing Company, Inc.,
1994.<!-- <br> --> ISBN 0-201-54777-5</para>
<para>Salus, Peter H. <emphasis>A quarter century of UNIX</emphasis>.
Addison-Wesley Publishing Company, Inc., 1994.<!-- <br> --> ISBN
0-201-54777-5</para>
</listitem>
<listitem>
<para>Simon Garfinkel, Daniel Weise, Steven Strassmann.
<emphasis>The UNIX-HATERS Handbook</emphasis>. IDG Books
Worldwide, Inc., 1994.<!-- <br> --> ISBN 1-56884-203-1</para>
<para>Simon Garfinkel, Daniel Weise, Steven Strassmann. <emphasis>The
UNIX-HATERS Handbook</emphasis>. IDG Books Worldwide, Inc.,
1994.<!-- <br> --> ISBN 1-56884-203-1</para>
</listitem>
<listitem>
<para>Don Libes, Sandy Ressler <emphasis>Life with
UNIX</emphasis> &mdash; special edition. Prentice-Hall, Inc.,
1989.<!-- <br> --> ISBN 0-13-536657-7</para>
<para>Don Libes, Sandy Ressler <emphasis>Life with UNIX</emphasis>
&mdash; special edition. Prentice-Hall, Inc., 1989.<!-- <br> -->
ISBN 0-13-536657-7</para>
</listitem>
<listitem>
<para><emphasis>The BSD family tree</emphasis>. 1997.<!-- <br>
--> <ulink
url="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/misc/bsd-family-tree">ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/misc/bsd-family-tree</ulink> or <ulink URL="file:/usr/share/misc/bsd-family-tree">local</ulink> on a FreeBSD-current machine.</para>
<para><emphasis>The BSD family tree</emphasis>. 1997.<!-- <br> -->
<ulink
url="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/misc/bsd-family-tree">ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/misc/bsd-family-tree</ulink> or <ulink URL="file:/usr/share/misc/bsd-family-tree">local</ulink> on a FreeBSD-current machine.</para>
</listitem>
<listitem>
<para><emphasis>The BSD Release Announcements
collection</emphasis>. 1997.<!-- <br> --> <ulink
<para><emphasis>The BSD Release Announcements collection</emphasis>.
1997.<!-- <br> --> <ulink
URL="http://www.de.FreeBSD.ORG/de/ftp/releases/">http://www.de.FreeBSD.ORG/de/ftp/releases/</ulink></para>
</listitem>
@ -487,19 +437,18 @@ url="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/misc/bsd-family
<listitem>
<para><emphasis>Old BSD releases from the Computer Systems Research
group (CSRG)</emphasis>. <ulink
url="http://www.mckusick.com/csrg/">http://www.mckusick.com/csrg/</ulink>: The 4CD set covers all BSD versions from 1BSD to 4.4BSD and 4.4BSD-Lite2 (but not 2.11BSD, unfortunately). As well, the last disk holds the final sources plus the SCCS files.</para>
url="http://www.mckusick.com/csrg/">http://www.mckusick.com/csrg/</ulink>:
The 4CD set covers all BSD versions from 1BSD to 4.4BSD and
4.4BSD-Lite2 (but not 2.11BSD, unfortunately). As well, the last
disk holds the final sources plus the SCCS files.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>Magazines and Journals</title>
<itemizedlist>
<listitem>
<para><emphasis>The C/C++ Users Journal</emphasis>. R&amp;D
Publications Inc. ISSN 1075-2838</para>
@ -510,13 +459,9 @@ url="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/misc/bsd-family
Administrators</emphasis> Miller Freeman, Inc., ISSN
1061-2688</para>
</listitem>
</itemizedlist>
</sect1>
</chapter>
</chapter>
<!--
Local Variables:

16
en_US.ISO8859-1/books/handbook/book.sgml
View file

@ -36,19 +36,21 @@
<abstract>
<para>Welcome to FreeBSD! This handbook covers the installation and day
to day use of <emphasis>FreeBSD Release &rel.current;</emphasis>. This
manual is a <emphasis>work in progress</emphasis> and is the work of
many individuals. Many sections do not yet exist and some of those
to day use of <emphasis>FreeBSD Release &rel.current;</emphasis>.
This manual is a <emphasis>work in progress</emphasis> and is the work
of many individuals. Many sections do not yet exist and some of those
that do exist need to be updated. If you are interested in helping
with this project, send email to the &a.doc;. The latest version of
this document is always available from the <ulink
URL="http://www.FreeBSD.ORG/">FreeBSD World Wide Web server</ulink>.
It may also be downloaded in <ulink url="handbook.latin1">plain
text</ulink>, <ulink url="handbook.ps">postscript</ulink> or <ulink
url="handbook-html.tar.gz">HTML</ulink> with HTTP or gzip'd from the <ulink
url="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/doc/">FreeBSD FTP server</ulink> or one of the numerous <link
text</ulink>, <ulink url="handbook.ps">postscript</ulink> or <ulink
url="handbook-html.tar.gz">HTML</ulink> with HTTP or gzip'd from the
<ulink url="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/doc/">FreeBSD FTP
server</ulink> or one of the numerous <link
linkend="mirrors-ftp">mirror sites</link>. You may also want to
<ulink URL="http://www.FreeBSD.ORG/search.html">Search the Handbook</ulink>.</para>
<ulink URL="http://www.FreeBSD.ORG/search.html">Search the
Handbook</ulink>.</para>
</abstract>
</bookinfo>

6188
en_US.ISO8859-1/books/handbook/contrib/chapter.sgml
View file

File diff suppressed because it is too large Load diff

1916
en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml
View file

File diff suppressed because it is too large Load diff

27
en_US.ISO8859-1/books/handbook/disks/chapter.sgml
View file

@ -11,8 +11,8 @@
<para>Login as user <username>root</username>. After you've installed the
drive, inspect <filename>/var/run/dmesg.boot</filename> to ensure the new
disk was found. Continuing with our example, the newly added drive will be
<filename>sd1</filename> and we want to mount it on
disk was found. Continuing with our example, the newly added drive will
be <filename>sd1</filename> and we want to mount it on
<filename>/1</filename>. (if you are adding an IDE drive substitute
<filename>wd</filename> for <filename>sd</filename>)</para>
@ -37,7 +37,7 @@
<sect1>
<title>Using sysinstall</title>
<para> You may use <command>/stand/sysinstall</command> to partition and
<para>You may use <command>/stand/sysinstall</command> to partition and
label a new disk using its easy to use menus. Either login as user
<username>root</username> or use the <command>su</command> command. Run
<command>/stand/sysinstall</command> and enter the
@ -56,19 +56,20 @@
<literal>YES</literal>. Write the changes to the disk using
<command>W</command>. Now exit the FDISK editor using
<command>q</command>. Next you will be asked about the Master Boot
Record. Since you are adding a disk to an already running system, choose
<literal>None</literal>.</para>
Record. Since you are adding a disk to an already running system,
choose <literal>None</literal>.</para>
<para>Next enter the <literal>Disk Label Editor</literal>. This is where
you will create the traditional BSD partitions. A disk can have up to
eight partitions, labeled a-h. A few of the partition labels have
special uses. The <literal>a</literal> partition is used for the root
partition (<filename>/</filename>). Thus only your system disk (e.g, the
disk you boot from) should have an <literal>a</literal> partition. The
<literal>b</literal> partition is used for swap partitions, and you may
have many disks with swap partitions. The <literal>c</literal> partition
addresses the entire disk in dedicated mode, or the entire FreeBSD slice
in slice mode. The other partitions are for general use.</para>
partition (<filename>/</filename>). Thus only your system disk (e.g,
the disk you boot from) should have an <literal>a</literal> partition.
The <literal>b</literal> partition is used for swap partitions, and you
may have many disks with swap partitions. The <literal>c</literal>
partition addresses the entire disk in dedicated mode, or the entire
FreeBSD slice in slice mode. The other partitions are for general
use.</para>
<para>Sysinstall's Label editor favors the <literal>e</literal> partition
for non-root, non-swap partitions. With in the Label editor, create a
@ -107,7 +108,6 @@
&ldquo;appropriate&rdquo; any partition it finds which it doesn't
understand.</para>
<screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/rsd1 bs=1k count=1</userinput>
&prompt.root; <userinput>disklabel -Brw sd1 auto</userinput>
&prompt.root; <userinput>disklabel -e sd</userinput>1 # create the `e' partition
@ -116,17 +116,14 @@
&prompt.root; <userinput>vi /etc/fstab</userinput> # add an entry for /dev/sd1e
&prompt.root; <userinput>mount /1</userinput></screen>
<para>An alternate method is:</para>
<screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/rsd1 count=2</userinput>
&prompt.root; <userinput>disklabel /dev/rsd1 | disklabel -BrR sd1 /dev/stdin</userinput>
&prompt.root; <userinput>newfs /dev/rsd1e</userinput>
&prompt.root; <userinput>mkdir -p /1</userinput>
&prompt.root; <userinput>vi /etc/fstab</userinput> # add an entry for /dev/sd1e
&prompt.root; <userinput>mount /1</userinput></screen>
</sect2>
</sect1>

672
en_US.ISO8859-1/books/handbook/eresources/chapter.sgml
View file

File diff suppressed because it is too large Load diff

4585
en_US.ISO8859-1/books/handbook/hw/chapter.sgml
View file

File diff suppressed because it is too large Load diff

886
en_US.ISO8859-1/books/handbook/install/chapter.sgml
View file

File diff suppressed because it is too large Load diff

760
en_US.ISO8859-1/books/handbook/introduction/chapter.sgml
View file

@ -1,170 +1,156 @@
<chapter id="introduction">
<chapter id="introduction">
<title>Introduction</title>
<para>FreeBSD is a 4.4BSD-Lite based operating system for Intel
architecture (x86) based PCs. For an overview of FreeBSD, see
<link linkend="nutshell">FreeBSD in a nutshell</link>. For a
history of the project, read <link linkend="history">a brief
history of FreeBSD</link>. To see a description of the latest release,
read <link linkend="relnotes">about the current
release</link>. If you're interested in contributing something to the
FreeBSD project (code, equipment, sacks of unmarked bills), please see
about <link linkend="contrib">contributing to FreeBSD</link>.</para>
<para>FreeBSD is a 4.4BSD-Lite based operating system for Intel architecture
(x86) based PCs. For an overview of FreeBSD, see <link
linkend="nutshell">FreeBSD in a nutshell</link>. For a history of the
project, read <link linkend="history">a brief history of FreeBSD</link>.
To see a description of the latest release, read <link
linkend="relnotes">about the current release</link>. If you're
interested in contributing something to the FreeBSD project (code,
equipment, sacks of unmarked bills), please see about <link
linkend="contrib">contributing to FreeBSD</link>.</para>
<sect1 id="nutshell">
<title>FreeBSD in a Nutshell</title>
<para>FreeBSD is a state of the art operating system for personal
computers based on the Intel CPU architecture, which includes the
386, 486 and Pentium processors (both SX and DX versions). Intel
compatible CPUs from AMD and Cyrix are supported as well. FreeBSD
provides you with many advanced features previously available only
on much more expensive computers. These features include:</para>
computers based on the Intel CPU architecture, which includes the 386,
486 and Pentium processors (both SX and DX versions). Intel compatible
CPUs from AMD and Cyrix are supported as well. FreeBSD provides you
with many advanced features previously available only on much more
expensive computers. These features include:</para>
<itemizedlist>
<listitem>
<para><emphasis>Preemptive multitasking</emphasis> with
dynamic priority adjustment to ensure smooth and fair sharing
of the computer between applications and users.</para>
<para><emphasis>Preemptive multitasking</emphasis> with dynamic
priority adjustment to ensure smooth and fair sharing of the
computer between applications and users.</para>
</listitem>
<listitem>
<para><emphasis>Multiuser</emphasis> access means that
many people can use a FreeBSD system simultaneously for a
variety of things. System peripherals such as printers and
tape drives are also properly SHARED BETWEEN ALL users on the
system.</para>
<para><emphasis>Multiuser</emphasis> access means that many people can
use a FreeBSD system simultaneously for a variety of things. System
peripherals such as printers and tape drives are also properly
SHARED BETWEEN ALL users on the system.</para>
</listitem>
<listitem>
<para>Complete <emphasis>TCP/IP networking</emphasis>
including SLIP, PPP, NFS and NIS support. This means that
your FreeBSD machine can inter-operate easily with other
systems as well act as an enterprise server, providing vital
functions such as NFS (remote file access) and e-mail services
or putting your organization on the Internet with WWW, ftp,
routing and firewall (security) services.</para>
<para>Complete <emphasis>TCP/IP networking</emphasis> including SLIP,
PPP, NFS and NIS support. This means that your FreeBSD machine can
inter-operate easily with other systems as well act as an enterprise
server, providing vital functions such as NFS (remote file access)
and e-mail services or putting your organization on the Internet
with WWW, ftp, routing and firewall (security) services.</para>
</listitem>
<listitem>
<para><emphasis>Memory protection</emphasis> ensures
that applications (or users) cannot interfere with each other.
One application crashing will not affect others in any
way.</para>
<para><emphasis>Memory protection</emphasis> ensures that applications
(or users) cannot interfere with each other. One application
crashing will not affect others in any way.</para>
</listitem>
<listitem>
<para>FreeBSD is a <emphasis>32-bit</emphasis>
operating system and was designed as such from the ground
up.</para>
<para>FreeBSD is a <emphasis>32-bit</emphasis> operating system and
was designed as such from the ground up.</para>
</listitem>
<listitem>
<para>The industry standard <emphasis>X Window
System</emphasis> (X11R6) provides a graphical user
interface (GUI) for the cost of a common VGA card and monitor
and comes with full sources.</para>
<para>The industry standard <emphasis>X Window System</emphasis>
(X11R6) provides a graphical user interface (GUI) for the cost of a
common VGA card and monitor and comes with full sources.</para>
</listitem>
<listitem>
<para><emphasis>Binary compatibility</emphasis> with
many programs built for SCO, BSDI, NetBSD, Linux and
386BSD.</para>
<para><emphasis>Binary compatibility</emphasis> with many programs
built for SCO, BSDI, NetBSD, Linux and 386BSD.</para>
</listitem>
<listitem>
<para>Hundreds of <emphasis>ready-to-run</emphasis>
applications are available from the FreeBSD <emphasis>ports</emphasis> and <emphasis>packages</emphasis> collection. Why search the net
when you can find it all right here?</para>
<para>Hundreds of <emphasis>ready-to-run</emphasis> applications are
available from the FreeBSD <emphasis>ports</emphasis> and
<emphasis>packages</emphasis> collection. Why search the net when
you can find it all right here?</para>
</listitem>
<listitem>
<para>Thousands of additional and <emphasis>easy-to-port</emphasis> applications available on
the Internet. FreeBSD is source code compatible with most
popular commercial Unix systems and thus most applications
require few, if any, changes to compile.</para>
<para>Thousands of additional and <emphasis>easy-to-port</emphasis>
applications available on the Internet. FreeBSD is source code
compatible with most popular commercial Unix systems and thus most
applications require few, if any, changes to compile.</para>
</listitem>
<listitem>
<para>Demand paged <emphasis>virtual memory</emphasis>
and &ldquo;merged VM/buffer cache&rdquo; design efficiently satisfies
applications with large appetites for memory while still
maintaining interactive response to other users.</para>
<para>Demand paged <emphasis>virtual memory</emphasis> and
&ldquo;merged VM/buffer cache&rdquo; design efficiently satisfies
applications with large appetites for memory while still maintaining
interactive response to other users.</para>
</listitem>
<listitem>
<para><emphasis>Shared libraries</emphasis> (the Unix
equivalent of MS-Windows DLLs) provide for efficient use of
disk space and memory.</para>
<para><emphasis>Shared libraries</emphasis> (the Unix equivalent of
MS-Windows DLLs) provide for efficient use of disk space and
memory.</para>
</listitem>
<listitem>
<para>A full complement of <emphasis>C</emphasis>,
<emphasis>C++</emphasis> and <emphasis>Fortran</emphasis> development tools. Many
additional languages for advanced research and development are
also available in the ports and packages collection.</para>
<emphasis>C++</emphasis> and <emphasis>Fortran</emphasis>
development tools. Many additional languages for advanced research
and development are also available in the ports and packages
collection.</para>
</listitem>
<listitem>
<para><emphasis>Source code</emphasis> for the entire
system means you have the greatest degree of control over your
environment. Why be locked into a proprietary solution and at
the mercy of your vendor when you can have a truly Open
System?</para>
<para><emphasis>Source code</emphasis> for the entire system means you
have the greatest degree of control over your environment. Why be
locked into a proprietary solution and at the mercy of your vendor
when you can have a truly Open System?</para>
</listitem>
<listitem>
<para>Extensive <emphasis>on-line
documentation</emphasis>.</para>
<para>Extensive <emphasis>on-line documentation</emphasis>.</para>
</listitem>
<listitem>
<para><emphasis>And many more!</emphasis></para>
</listitem>
</itemizedlist>
<para>FreeBSD is based on the 4.4BSD-Lite release from Computer Systems
Research Group (CSRG) at the University of California at Berkeley, and
carries on the distinguished tradition of BSD systems development. In
addition to the fine work provided by CSRG, the FreeBSD Project has put
in many thousands of hours in fine tuning the system for maximum
performance and reliability in real-life load situations. As many of
the commercial giants struggle to field PC operating systems with such
features, performance and reliability, FreeBSD can offer them
<emphasis>now</emphasis>!</para>
<para>FreeBSD is based on the 4.4BSD-Lite release from Computer
Systems Research Group (CSRG) at the University of California at
Berkeley, and carries on the distinguished tradition of BSD systems
development. In addition to the fine work provided by CSRG, the
FreeBSD Project has put in many thousands of hours in fine tuning
the system for maximum performance and reliability in real-life load
situations. As many of the commercial giants struggle to field PC
operating systems with such features, performance and reliability,
FreeBSD can offer them <emphasis>now</emphasis>!</para>
<para>The applications to which FreeBSD can be put are truly limited
only by your own imagination. From software development to factory
automation, inventory control to azimuth correction of remote
satellite antennae; if it can be done with a commercial UNIX product
then it is more than likely that you can do it with FreeBSD, too!
FreeBSD also benefits significantly from the literally thousands of
high quality applications developed by research centers and
universities around the world, often available at little to no cost.
Commercial applications are also available and appearing in greater
numbers every day.</para>
<para>Because the source code for FreeBSD itself is generally
available, the system can also be customized to an almost unheard of
degree for special applications or projects, and in ways not
generally possible with operating systems from most major commercial
vendors. Here is just a sampling of some of the applications in
which people are currently using FreeBSD:</para>
<para>The applications to which FreeBSD can be put are truly limited only
by your own imagination. From software development to factory
automation, inventory control to azimuth correction of remote satellite
antennae; if it can be done with a commercial UNIX product then it is
more than likely that you can do it with FreeBSD, too! FreeBSD also
benefits significantly from the literally thousands of high quality
applications developed by research centers and universities around the
world, often available at little to no cost. Commercial applications are
also available and appearing in greater numbers every day.</para>
<para>Because the source code for FreeBSD itself is generally available,
the system can also be customized to an almost unheard of degree for
special applications or projects, and in ways not generally possible
with operating systems from most major commercial vendors. Here is just
a sampling of some of the applications in which people are currently
using FreeBSD:</para>
<itemizedlist>
<listitem>
<para><emphasis>Internet Services:</emphasis> The
robust TCP/IP networking built into FreeBSD makes it an ideal
platform for a variety of Internet services such as:</para>
<itemizedlist>
<para><emphasis>Internet Services:</emphasis> The robust TCP/IP
networking built into FreeBSD makes it an ideal platform for a
variety of Internet services such as:</para>
<itemizedlist>
<listitem>
<para>FTP servers</para>
</listitem>
@ -192,71 +178,62 @@
<listitem>
<para>And more...</para>
</listitem>
</itemizedlist>
<para>You can easily start out small with an
inexpensive 386 class PC and upgrade as your enterprise
grows.</para>
<para>You can easily start out small with an inexpensive 386 class PC
and upgrade as your enterprise grows.</para>
</listitem>
<listitem>
<para><emphasis>Education:</emphasis> Are you a student
of computer science or a related engineering field? There is
no better way of learning about operating systems, computer
architecture and networking than the hands on, under the hood
experience that FreeBSD can provide. A number of freely
available CAD, mathematical and graphic design packages also
make it highly useful to those whose primary interest in a
computer is to get <emphasis>other</emphasis> work
done!</para>
<para><emphasis>Education:</emphasis> Are you a student of computer
science or a related engineering field? There is no better way of
learning about operating systems, computer architecture and
networking than the hands on, under the hood experience that FreeBSD
can provide. A number of freely available CAD, mathematical and
graphic design packages also make it highly useful to those whose
primary interest in a computer is to get <emphasis>other</emphasis>
work done!</para>
</listitem>
<listitem>
<para><emphasis>Research:</emphasis> With source code
for the entire system available, FreeBSD is an excellent
platform for research in operating systems as well as other
branches of computer science. FreeBSD's freely available
nature also makes it possible for remote groups to collaborate
on ideas or shared development without having to worry about
special licensing agreements or limitations on what may be
discussed in open forums.</para>
<para><emphasis>Research:</emphasis> With source code for the entire
system available, FreeBSD is an excellent platform for research in
operating systems as well as other branches of computer science.
FreeBSD's freely available nature also makes it possible for remote
groups to collaborate on ideas or shared development without having
to worry about special licensing agreements or limitations on what
may be discussed in open forums.</para>
</listitem>
<listitem>
<para><emphasis>Networking:</emphasis> Need a new
router? A name server (DNS)? A firewall to keep people out
of your internal network? FreeBSD can easily turn that unused
386 or 486 PC sitting in the corner into an advanced router
with sophisticated packet filtering capabilities.</para>
<para><emphasis>Networking:</emphasis> Need a new router? A name
server (DNS)? A firewall to keep people out of your internal
network? FreeBSD can easily turn that unused 386 or 486 PC sitting
in the corner into an advanced router with sophisticated packet
filtering capabilities.</para>
</listitem>
<listitem>
<para><emphasis>X Window workstation:</emphasis>
FreeBSD is a fine choice for an inexpensive X terminal
solution, either using the freely available XFree86 server or
one of the excellent commercial servers provided by X Inside.
Unlike an X terminal, FreeBSD allows many applications to be
run locally, if desired, thus relieving the burden on a
central server. FreeBSD can even boot &ldquo;diskless&rdquo;, making
individual workstations even cheaper and easier to
administer.</para>
<para><emphasis>X Window workstation:</emphasis> FreeBSD is a fine
choice for an inexpensive X terminal solution, either using the
freely available XFree86 server or one of the excellent commercial
servers provided by X Inside. Unlike an X terminal, FreeBSD allows
many applications to be run locally, if desired, thus relieving the
burden on a central server. FreeBSD can even boot
&ldquo;diskless&rdquo;, making individual workstations even cheaper
and easier to administer.</para>
</listitem>
<listitem>
<para><emphasis>Software Development:</emphasis> The
basic FreeBSD system comes with a full complement of
development tools including the renowned GNU C/C++ compiler
and debugger.</para>
<para><emphasis>Software Development:</emphasis> The basic FreeBSD
system comes with a full complement of development tools including
the renowned GNU C/C++ compiler and debugger.</para>
</listitem>
</itemizedlist>
<para>FreeBSD is available in both source and binary form on CDROM and
via anonymous ftp. See <link linkend="mirrors">Obtaining
FreeBSD</link> for more details.</para>
<para>FreeBSD is available in both source and binary form on CDROM and via
anonymous ftp. See <link linkend="mirrors">Obtaining FreeBSD</link>
for more details.</para>
</sect1>
<sect1 id="history">
@ -265,101 +242,96 @@
<para><emphasis>Contributed by &a.jkh;</emphasis>.</para>
<para>The FreeBSD project had its genesis in the early part of 1993,
partially as an outgrowth of the &ldquo;Unofficial 386BSD Patchkit&rdquo; by the
patchkit's last 3 coordinators: Nate Williams, Rod Grimes and
myself.</para>
partially as an outgrowth of the &ldquo;Unofficial 386BSD
Patchkit&rdquo; by the patchkit's last 3 coordinators: Nate Williams,
Rod Grimes and myself.</para>
<para>Our original goal was to produce an intermediate snapshot of
386BSD in order to fix a number of problems with it that the
patchkit mechanism just was not capable of solving. Some of you may
remember the early working title for the project being &ldquo;386BSD 0.5&rdquo;
or &ldquo;386BSD Interim&rdquo; in reference to that fact.</para>
<para>Our original goal was to produce an intermediate snapshot of 386BSD
in order to fix a number of problems with it that the patchkit mechanism
just was not capable of solving. Some of you may remember the early
working title for the project being &ldquo;386BSD 0.5&rdquo; or
&ldquo;386BSD Interim&rdquo; in reference to that fact.</para>
<para>386BSD was Bill Jolitz's operating system, which had been up to
that point suffering rather severely from almost a year's worth of
neglect. As the patchkit swelled ever more uncomfortably with each
passing day, we were in unanimous agreement that something had to be
done and decided to try and assist Bill by providing this interim
&ldquo;cleanup&rdquo; snapshot. Those plans came to a rude halt when Bill
Jolitz suddenly decided to withdraw his sanction from the project
and without any clear indication of what would be done
instead.</para>
<para>386BSD was Bill Jolitz's operating system, which had been up to that
point suffering rather severely from almost a year's worth of neglect.
As the patchkit swelled ever more uncomfortably with each passing day,
we were in unanimous agreement that something had to be done and decided
to try and assist Bill by providing this interim &ldquo;cleanup&rdquo;
snapshot. Those plans came to a rude halt when Bill Jolitz suddenly
decided to withdraw his sanction from the project and without any clear
indication of what would be done instead.</para>
<para>It did not take us long to decide that the goal remained
worthwhile, even without Bill's support, and so we adopted the name
&ldquo;FreeBSD&rdquo;, coined by David Greenman. Our initial objectives were
set after consulting with the system's current users and, once it
became clear that the project was on the road to perhaps even
becoming a reality, I contacted Walnut Creek CDROM with an eye
towards improving FreeBSD's distribution channels for those many
unfortunates without easy access to the Internet. Walnut Creek
CDROM not only supported the idea of distributing FreeBSD on CD but
went so far as to provide the project with a machine to work on and
a fast Internet connection. Without Walnut Creek CDROM's almost
unprecedented degree of faith in what was, at the time, a completely
unknown project, it is quite unlikely that FreeBSD would have gotten
as far, as fast, as it has today.</para>
<para>It did not take us long to decide that the goal remained worthwhile,
even without Bill's support, and so we adopted the name
&ldquo;FreeBSD&rdquo;, coined by David Greenman. Our initial objectives
were set after consulting with the system's current users and, once it
became clear that the project was on the road to perhaps even becoming a
reality, I contacted Walnut Creek CDROM with an eye towards improving
FreeBSD's distribution channels for those many unfortunates without easy
access to the Internet. Walnut Creek CDROM not only supported the idea
of distributing FreeBSD on CD but went so far as to provide the project
with a machine to work on and a fast Internet connection. Without
Walnut Creek CDROM's almost unprecedented degree of faith in what was,
at the time, a completely unknown project, it is quite unlikely that
FreeBSD would have gotten as far, as fast, as it has today.</para>
<para>The first CDROM (and general net-wide) distribution was FreeBSD
1.0, released in December of 1993. This was based on the
4.3BSD-Lite (&ldquo;Net/2&rdquo;) tape from U.C. Berkeley, with many components
also provided by 386BSD and the Free Software Foundation. It was a
fairly reasonable success for a first offering, and we followed it
with the highly successful FreeBSD 1.1 release in May of
1994.</para>
<para>The first CDROM (and general net-wide) distribution was FreeBSD 1.0,
released in December of 1993. This was based on the 4.3BSD-Lite
(&ldquo;Net/2&rdquo;) tape from U.C. Berkeley, with many components also
provided by 386BSD and the Free Software Foundation. It was a fairly
reasonable success for a first offering, and we followed it with the
highly successful FreeBSD 1.1 release in May of 1994.</para>
<para>Around this time, some rather unexpected storm clouds formed on
the horizon as Novell and U.C. Berkeley settled their long-running
lawsuit over the legal status of the Berkeley Net/2 tape. A
condition of that settlement was U.C. Berkeley's concession that
large parts of Net/2 were &ldquo;encumbered&rdquo; code and the property of
Novell, who had in turn acquired it from AT&amp;T some time
previously. What Berkeley got in return was Novell's &ldquo;blessing&rdquo;
that the 4.4BSD-Lite release, when it was finally released, would be
declared unencumbered and all existing Net/2 users would be strongly
encouraged to switch. This included FreeBSD, and the project was
given until the end of July 1994 to stop shipping its own Net/2
based product. Under the terms of that agreement, the project was
allowed one last release before the deadline, that release being
FreeBSD 1.1.5.1.</para>
<para>Around this time, some rather unexpected storm clouds formed on the
horizon as Novell and U.C. Berkeley settled their long-running lawsuit
over the legal status of the Berkeley Net/2 tape. A condition of that
settlement was U.C. Berkeley's concession that large parts of Net/2 were
&ldquo;encumbered&rdquo; code and the property of Novell, who had in
turn acquired it from AT&amp;T some time previously. What Berkeley got
in return was Novell's &ldquo;blessing&rdquo; that the 4.4BSD-Lite
release, when it was finally released, would be declared unencumbered
and all existing Net/2 users would be strongly encouraged to switch.
This included FreeBSD, and the project was given until the end of July
1994 to stop shipping its own Net/2 based product. Under the terms of
that agreement, the project was allowed one last release before the
deadline, that release being FreeBSD 1.1.5.1.</para>
<para>FreeBSD then set about the arduous task of literally
re-inventing itself from a completely new and rather incomplete set
of 4.4BSD-Lite bits. The &ldquo;Lite&rdquo; releases were light in part because
Berkeley's CSRG had removed large chunks of code required for
actually constructing a bootable running system (due to various
legal requirements) and the fact that the Intel port of 4.4 was
highly incomplete. It took the project until December of 1994 to
make this transition, and in January of 1995 it released FreeBSD 2.0
to the net and on CDROM. Despite being still more than a little
rough around the edges, the release was a significant success and
was followed by the more robust and easier to install FreeBSD 2.0.5
release in June of 1995.</para>
<para>FreeBSD then set about the arduous task of literally re-inventing
itself from a completely new and rather incomplete set of 4.4BSD-Lite
bits. The &ldquo;Lite&rdquo; releases were light in part because
Berkeley's CSRG had removed large chunks of code required for actually
constructing a bootable running system (due to various legal
requirements) and the fact that the Intel port of 4.4 was highly
incomplete. It took the project until December of 1994 to make this
transition, and in January of 1995 it released FreeBSD 2.0 to the net
and on CDROM. Despite being still more than a little rough around the
edges, the release was a significant success and was followed by the
more robust and easier to install FreeBSD 2.0.5 release in June of
1995.</para>
<para>We released FreeBSD 2.1.5 in August of 1996, and it appeared to
be popular enough among the ISP and commercial communities that
another release along the 2.1-stable branch was merited. This was
FreeBSD 2.1.7.1, released in February 1997 and capping the end of
mainstream development on 2.1-stable. Now in maintenance mode, only
security enhancements and other critical bug fixes will be done on
this branch (RELENG_2_1_0).</para>
<para>We released FreeBSD 2.1.5 in August of 1996, and it appeared to be
popular enough among the ISP and commercial communities that another
release along the 2.1-stable branch was merited. This was FreeBSD
2.1.7.1, released in February 1997 and capping the end of mainstream
development on 2.1-stable. Now in maintenance mode, only security
enhancements and other critical bug fixes will be done on this branch
(RELENG_2_1_0).</para>
<para>FreeBSD 2.2 was branched from the development mainline
(&ldquo;-current&rdquo;) in November 1996 as the RELENG_2_2 branch, and the
first full release (2.2.1) was released in April, 1997. Further
releases along the 2.2 branch were done in the Summer and Fall of
'97, the latest being 2.2.7 which appeared in late July of '98.
The first official 3.0 release appeared in October, 1998 and the
last release on the 2.2 branch, 2.2.8, appeared in November,
1998.</para>
(&ldquo;-current&rdquo;) in November 1996 as the RELENG_2_2 branch, and
the first full release (2.2.1) was released in April, 1997. Further
releases along the 2.2 branch were done in the Summer and Fall of '97,
the latest being 2.2.7 which appeared in late July of '98. The first
official 3.0 release appeared in October, 1998 and the last release on
the 2.2 branch, 2.2.8, appeared in November, 1998.</para>
<para>The tree branched again on Jan 20, 1999. This led to
4.0-current and a 3.x-stable branch, from which 3.1 will be
released on February 15th, 1999.</para>
<para>The tree branched again on Jan 20, 1999. This led to 4.0-current
and a 3.x-stable branch, from which 3.1 will be released on February
15th, 1999.</para>
<para>Long term development projects will continue to take place in
the 4.0-current branch and SNAPshot releases of 4.0 on CDROM (and,
of course, on the net).</para>
<para>Long term development projects will continue to take place in the
4.0-current branch and SNAPshot releases of 4.0 on CDROM (and, of
course, on the net).</para>
</sect1>
<sect1 id="goals">
@ -367,25 +339,24 @@
<para><emphasis>Contributed by &a.jkh;</emphasis>.</para>
<para>The goals of the FreeBSD Project are to provide software that
may be used for any purpose and without strings attached. Many of
us have a significant investment in the code (and project) and would
certainly not mind a little financial compensation now and then, but
we're definitely not prepared to insist on it. We believe that our
first and foremost &ldquo;mission&rdquo; is to provide code to any and all
comers, and for whatever purpose, so that the code gets the widest
possible use and provides the widest possible benefit. This is, I
believe, one of the most fundamental goals of Free Software and one
that we enthusiastically support.</para>
<para>The goals of the FreeBSD Project are to provide software that may be
used for any purpose and without strings attached. Many of us have a
significant investment in the code (and project) and would certainly not
mind a little financial compensation now and then, but we're definitely
not prepared to insist on it. We believe that our first and foremost
&ldquo;mission&rdquo; is to provide code to any and all comers, and for
whatever purpose, so that the code gets the widest possible use and
provides the widest possible benefit. This is, I believe, one of the
most fundamental goals of Free Software and one that we enthusiastically
support.</para>
<para>That code in our source tree which falls under the GNU Public
License (GPL) or GNU Library Public License (GLPL) comes with
slightly more strings attached, though at least on the side of
enforced access rather than the usual opposite. Due to the
additional complexities that can evolve in the commercial use of GPL
software, we do, however, endeavor to replace such software with
submissions under the more relaxed BSD copyright whenever possible.</para>
License (GPL) or GNU Library Public License (GLPL) comes with slightly
more strings attached, though at least on the side of enforced access
rather than the usual opposite. Due to the additional complexities that
can evolve in the commercial use of GPL software, we do, however,
endeavor to replace such software with submissions under the more
relaxed BSD copyright whenever possible.</para>
</sect1>
<sect1 id="development">
@ -396,222 +367,225 @@
<para>The development of FreeBSD is a very open and flexible process,
FreeBSD being literally built from the contributions of hundreds of
people around the world, as can be seen from our <link
linkend="staff">list of contributors</link>. We are constantly
on the lookout for new developers and ideas, and those interested in
becoming more closely involved with the project need simply contact
us at the &a.hackers;. Those who prefer to work more independently
are also accommodated, and they are free to use our FTP facilities
at <ulink
URL="ftp://ftp.freebsd.org/pub/FreeBSD/incoming">ftp.freebsd.org</ulink> to distribute their own patches or work-in-progress sources. The &a.announce; is also available to those wishing to make other FreeBSD users aware of major areas of work.</para>
<para>Useful things to know about the FreeBSD project and its
development process, whether working independently or in close
cooperation:</para>
linkend="staff">list of contributors</link>. We are constantly on the
lookout for new developers and ideas, and those interested in becoming
more closely involved with the project need simply contact us at the
&a.hackers;. Those who prefer to work more independently are also
accommodated, and they are free to use our FTP facilities at <ulink
URL="ftp://ftp.freebsd.org/pub/FreeBSD/incoming">ftp.freebsd.org</ulink>
to distribute their own patches or work-in-progress sources. The
&a.announce; is also available to those wishing to make other FreeBSD
users aware of major areas of work.</para>
<para>Useful things to know about the FreeBSD project and its development
process, whether working independently or in close cooperation:</para>
<variablelist>
<varlistentry><term>The CVS
repository<anchor id="development-cvs-repository"></term>
<varlistentry>
<term>The CVS repository<anchor
id="development-cvs-repository"></term>
<listitem>
<para>The central source tree for FreeBSD is maintained by
<ulink
URL="http://www.cyclic.com/cyclic-pages/CVS-sheet.html">CVS</ulink> (Concurrent Version System), a freely available source code control tool which comes bundled with FreeBSD. The primary <ulink URL="http://www.freebsd.org/cgi/cvsweb.cgi">CVS repository</ulink> resides on a machine in Concord CA, USA from where it is replicated to numerous mirror machines throughout the world. The CVS tree, as well as the <link linkend="current">-current</link> and <link
linkend="stable">-stable</link> trees which are checked
out of it, can be easily replicated to your own machine as
well. Please refer to the
<link linkend="synching">Synchronizing your source
<para>The central source tree for FreeBSD is maintained by <ulink
URL="http://www.cyclic.com/cyclic-pages/CVS-sheet.html">CVS</ulink>
(Concurrent Version System), a freely available source code
control tool which comes bundled with FreeBSD. The primary <ulink
URL="http://www.freebsd.org/cgi/cvsweb.cgi">CVS
repository</ulink> resides on a machine in Concord CA, USA from
where it is replicated to numerous mirror machines throughout the
world. The CVS tree, as well as the <link
linkend="current">-current</link> and <link
linkend="stable">-stable</link> trees which are checked out of
it, can be easily replicated to your own machine as well. Please
refer to the <link linkend="synching">Synchronizing your source
tree</link> section for more information on doing this.</para>
</listitem>
</varlistentry>
<varlistentry><term>The committers
list<anchor id="development-committers"></term>
<varlistentry>
<term>The committers list<anchor id="development-committers"></term>
<listitem>
<para>The <link linkend="staff-committers">committers</link>
are the people who have <emphasis>write</emphasis> access to
the CVS tree, and are thus authorized to make modifications
to the FreeBSD source (the term &ldquo;committer&rdquo; comes from the
&man.cvs.1; <command>commit</command> command, which is used to
bring new changes into the CVS repository). The best way of
making submissions for review by the committers list is to
use the &man.send-pr.1; command, though if something appears to be jammed in the system then you may also reach them by sending mail to <email>committers@freebsd.org</email>.</para>
<para>The <link linkend="staff-committers">committers</link> are the
people who have <emphasis>write</emphasis> access to the CVS tree,
and are thus authorized to make modifications to the FreeBSD
source (the term &ldquo;committer&rdquo; comes from the
&man.cvs.1; <command>commit</command> command, which is used
to bring new changes into the CVS repository). The best way of
making submissions for review by the committers list is to use the
&man.send-pr.1; command, though if something appears to be
jammed in the system then you may also reach them by sending mail
to <email>committers@freebsd.org</email>.</para>
</listitem>
</varlistentry>
<varlistentry><term>The FreeBSD core
team<anchor id="development-core"></term>
<varlistentry>
<term>The FreeBSD core team<anchor id="development-core"></term>
<listitem>
<para>The <link linkend="staff-core">FreeBSD core
team</link> would be equivalent to the board of directors if
the FreeBSD Project were a company. The primary task of the
core team is to make sure the project, as a whole, is in
good shape and is heading in the right directions. Inviting
dedicated and responsible developers to join our group of
committers is one of the functions of the core team, as is
the recruitment of new core team members as others move on.
Most current members of the core team started as committers
who's addiction to the project got the better of
<para>The <link linkend="staff-core">FreeBSD core team</link> would
be equivalent to the board of directors if the FreeBSD Project
were a company. The primary task of the core team is to make sure
the project, as a whole, is in good shape and is heading in the
right directions. Inviting dedicated and responsible developers
to join our group of committers is one of the functions of the
core team, as is the recruitment of new core team members as
others move on. Most current members of the core team started as
committers who's addiction to the project got the better of
them.</para>
<para>Some core team members also have specific <link
linkend="staff-who">areas of responsibility</link>,
meaning that they are committed to ensuring that some large
portion of the system works as advertised.</para>
linkend="staff-who">areas of responsibility</link>, meaning that
they are committed to ensuring that some large portion of the
system works as advertised.</para>
<note>
<para>Most members of the core team are volunteers when it
comes to FreeBSD development and do not benefit from the
project financially, so &ldquo;commitment&rdquo; should also not be
<para>Most members of the core team are volunteers when it comes
to FreeBSD development and do not benefit from the project
financially, so &ldquo;commitment&rdquo; should also not be
misconstrued as meaning &ldquo;guaranteed support.&rdquo; The
&ldquo;board of directors&rdquo; analogy above is not
actually very accurate, and it may be more suitable to say
that these are the people who gave up their lives in favor
of FreeBSD against their better judgement! <!-- smiley --><emphasis>;)</emphasis></para>
&ldquo;board of directors&rdquo; analogy above is not actually
very accurate, and it may be more suitable to say that these are
the people who gave up their lives in favor of FreeBSD against
their better judgement! <!-- smiley
--><emphasis>;)</emphasis></para>
</note>
</listitem>
</varlistentry>
<varlistentry><term>Outside
contributors</term>
<varlistentry>
<term>Outside contributors</term>
<listitem>
<para>Last, but definitely not least, the largest group of
developers are the users themselves who provide feedback and
bug-fixes to us on an almost constant basis. The primary
way of keeping in touch with FreeBSD's more non-centralized
development is to subscribe to the &a.hackers; (see <link
linkend="eresources-mail">mailing list
info</link>) where such things are discussed.</para>
bug-fixes to us on an almost constant basis. The primary way of
keeping in touch with FreeBSD's more non-centralized development
is to subscribe to the &a.hackers; (see <link
linkend="eresources-mail">mailing list info</link>) where such
things are discussed.</para>
<para><link linkend="contrib-additional">The list</link> of
those who have contributed something which made its way into
our source tree is a long and growing one, so why not join
it by contributing something back to FreeBSD today?
<!-- smiley --><emphasis>:-)</emphasis></para>
<para><link linkend="contrib-additional">The list</link> of those
who have contributed something which made its way into our source
tree is a long and growing one, so why not join it by contributing
something back to FreeBSD today? <!-- smiley
--><emphasis>:-)</emphasis></para>
<para>Providing code is not the only way of contributing to
the project; for a more complete list of things that need
doing, please refer to the <link linkend="contrib">how to
<para>Providing code is not the only way of contributing to the
project; for a more complete list of things that need doing,
please refer to the <link linkend="contrib">how to
contribute</link> section in this handbook.</para>
</listitem>
</varlistentry>
</variablelist>
<para>In summary, our development model is organized as a loose set of
concentric circles. The centralized model is designed for the
convenience of the <emphasis>users</emphasis> of FreeBSD, who are
thereby provided with an easy way of tracking one central code base,
not to keep potential contributors out! Our desire is to present a
stable operating system with a large set of coherent <link
linkend="ports">application programs</link> that the users can easily install
and use, and this model works very well in accomplishing
thereby provided with an easy way of tracking one central code base, not
to keep potential contributors out! Our desire is to present a stable
operating system with a large set of coherent <link
linkend="ports">application programs</link> that the users can easily
install and use, and this model works very well in accomplishing
that.</para>
<para>All we ask of those who would join us as FreeBSD developers is
some of the same dedication its current people have to its continued
<para>All we ask of those who would join us as FreeBSD developers is some
of the same dedication its current people have to its continued
success!</para>
</sect1>
<sect1 id="relnotes">
<title>About the Current Release</title>
<para>FreeBSD is a freely available, full source 4.4BSD-Lite based
release for Intel i386/i486/Pentium/PentiumPro/Pentium II (or
compatible) based PC's. It is based primarily on software from U.C.
Berkeley's CSRG group, with some enhancements from NetBSD, OpenBSD,
386BSD, and the Free Software Foundation.</para>
<para>FreeBSD is a freely available, full source 4.4BSD-Lite based release
for Intel i386/i486/Pentium/PentiumPro/Pentium II (or compatible) based
PC's. It is based primarily on software from U.C. Berkeley's CSRG
group, with some enhancements from NetBSD, OpenBSD, 386BSD, and the Free
Software Foundation.</para>
<para>Since our release of FreeBSD 2.0 in January of 95, the
performance, feature set, and stability of FreeBSD has improved
dramatically. The largest change is a revamped virtual memory
system with a merged VM/file buffer cache that not only increases
performance, but reduces FreeBSD's memory footprint, making a 5MB
configuration a more acceptable minimum. Other enhancements include
full NIS client and server support, transaction TCP support,
dial-on-demand PPP, an improved SCSI subsystem, early ISDN support,
support for FDDI and Fast Ethernet (100Mbit) adapters, improved
support for the Adaptec 2940 (WIDE and narrow) and many hundreds of
bug fixes.</para>
<para>Since our release of FreeBSD 2.0 in January of 95, the performance,
feature set, and stability of FreeBSD has improved dramatically. The
largest change is a revamped virtual memory system with a merged VM/file
buffer cache that not only increases performance, but reduces FreeBSD's
memory footprint, making a 5MB configuration a more acceptable minimum.
Other enhancements include full NIS client and server support,
transaction TCP support, dial-on-demand PPP, an improved SCSI subsystem,
early ISDN support, support for FDDI and Fast Ethernet (100Mbit)
adapters, improved support for the Adaptec 2940 (WIDE and narrow) and
many hundreds of bug fixes.</para>
<para>We have also taken the comments and suggestions of many of our
users to heart and have attempted to provide what we hope is a more
sane and easily understood installation process. Your feedback on
this (constantly evolving) process is especially welcome!</para>
<para>We have also taken the comments and suggestions of many of our users
to heart and have attempted to provide what we hope is a more sane and
easily understood installation process. Your feedback on this
(constantly evolving) process is especially welcome!</para>
<para>In addition to the base distributions, FreeBSD offers a new
ported software collection with hundreds of commonly sought-after
programs. At the end of August 1998 there were more than 1700 ports!
The list of ports ranges from http (WWW) servers, to games,
languages, editors and almost everything in between. The entire
ports collection requires approximately 26MB of storage, all ports
being expressed as &ldquo;deltas&rdquo; to their original sources. This
makes it much easier for us to update ports, and greatly reduces
the disk space demands made by the older 1.0 ports collection. To
compile a port, you simply change to the directory of the program
you wish to install, type <command>make all</command> followed by <command>make install</command>
after successful compilation and let the system do the rest. The
full original distribution for each port you build is retrieved
dynamically off the CDROM or a local ftp site, so you need only
enough disk space to build the ports you want. (Almost) every port
is also provided as a pre-compiled &ldquo;package&rdquo; which can be installed
with a simple command (pkg_add) by those who do not wish to compile
their own ports from source.</para>
<para>A number of additional documents which you may find very helpful
in the process of installing and using FreeBSD may now also be found
in the <filename>/usr/share/doc</filename> directory on any machine
running FreeBSD 2.1 or later. You may view the locally installed
manuals with any HTML capable browser using the following
URLs:</para>
<para>In addition to the base distributions, FreeBSD offers a new ported
software collection with hundreds of commonly sought-after programs. At
the end of August 1998 there were more than 1700 ports! The list of
ports ranges from http (WWW) servers, to games, languages, editors and
almost everything in between. The entire ports collection requires
approximately 26MB of storage, all ports being expressed as
&ldquo;deltas&rdquo; to their original sources. This makes it much
easier for us to update ports, and greatly reduces the disk space
demands made by the older 1.0 ports collection. To compile a port, you
simply change to the directory of the program you wish to install, type
<command>make all</command> followed by <command>make install</command>
after successful compilation and let the system do the rest. The full
original distribution for each port you build is retrieved dynamically
off the CDROM or a local ftp site, so you need only enough disk space to
build the ports you want. (Almost) every port is also provided as a
pre-compiled &ldquo;package&rdquo; which can be installed with a simple
command (pkg_add) by those who do not wish to compile their own ports
from source.</para>
<para>A number of additional documents which you may find very helpful in
the process of installing and using FreeBSD may now also be found in the
<filename>/usr/share/doc</filename> directory on any machine running
FreeBSD 2.1 or later. You may view the locally installed manuals with
any HTML capable browser using the following URLs:</para>
<variablelist>
<varlistentry><term>The FreeBSD handbook</term>
<varlistentry>
<term>The FreeBSD handbook</term>
<listitem>
<para><ulink
URL="file:/usr/share/doc/handbook/handbook.html">file:/usr/share/doc/handbook/handbook.html</ulink></para>
</listitem>
</varlistentry>
<varlistentry><term>The FreeBSD FAQ</term>
<varlistentry>
<term>The FreeBSD FAQ</term>
<listitem>
<para><ulink
URL="file:/usr/share/doc/FAQ/FAQ.html">file:/usr/share/doc/FAQ/FAQ.html</ulink></para>
</listitem>
</varlistentry>
</variablelist>
<para>You can also visit the master (and most frequently updated)
copies at <ulink
URL="http://www.freebsd.org">http://www.freebsd.org</ulink>.</para>
<para>The core of FreeBSD does not contain DES code which would
inhibit its being exported outside the United States. There is an
add-on package to the core distribution, for use only in the United
States, that contains the programs that normally use DES. The
auxiliary packages provided separately can be used by anyone. A
freely (from outside the U.S.) exportable European distribution of
DES for our non-U.S. users also exists and is described in the
<ulink URL="../FAQ/FAQ.html">FreeBSD FAQ</ulink>.</para>
<para>If password security for FreeBSD is all you need, and you have
no requirement for copying encrypted passwords from different hosts
(Suns, DEC machines, etc) into FreeBSD password entries, then
FreeBSD's MD5 based security may be all you require! We feel that
our default security model is more than a match for DES, and without
any messy export issues to deal with. If you are outside (or even
inside) the U.S., give it a try!</para>
<para>The core of FreeBSD does not contain DES code which would inhibit
its being exported outside the United States. There is an add-on
package to the core distribution, for use only in the United States,
that contains the programs that normally use DES. The auxiliary
packages provided separately can be used by anyone. A freely (from
outside the U.S.) exportable European distribution of DES for our
non-U.S. users also exists and is described in the <ulink
URL="../FAQ/FAQ.html">FreeBSD FAQ</ulink>.</para>
<para>If password security for FreeBSD is all you need, and you have no
requirement for copying encrypted passwords from different hosts (Suns,
DEC machines, etc) into FreeBSD password entries, then FreeBSD's MD5
based security may be all you require! We feel that our default security
model is more than a match for DES, and without any messy export issues
to deal with. If you are outside (or even inside) the U.S., give it a
try!</para>
</sect1>
</chapter>
</chapter>
<!--
Local Variables:

1684
en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml
View file

File diff suppressed because it is too large Load diff

540
en_US.ISO8859-1/books/handbook/kerneldebug/chapter.sgml
View file

@ -1,95 +1,87 @@
<chapter id="kerneldebug">
<chapter id="kerneldebug">
<title>Kernel Debugging</title>
<para><emphasis>Contributed by &a.paul; and &a.joerg;</emphasis></para>
<sect1>
<title>Debugging a Kernel Crash Dump with <command>kgdb</command></title>
<para>Here are some instructions for getting kernel debugging working
on a crash dump. They assume that you have enough swap space for a
crash dump. If you have multiple swap partitions and the first one
is too small to hold the dump, you can configure your kernel to use
an alternate dump device (in the <literal>config
kernel</literal> line), or you can specify an alternate using the
&man.dumpon.8; command. The best way to use &man.dumpon.8; is to set the <literal>dumpdev</literal> variable in
<para>Here are some instructions for getting kernel debugging working on a
crash dump. They assume that you have enough swap space for a crash
dump. If you have multiple swap partitions and the first one is too
small to hold the dump, you can configure your kernel to use an
alternate dump device (in the <literal>config kernel</literal> line), or
you can specify an alternate using the
&man.dumpon.8; command. The best way to use &man.dumpon.8; is to set
the <literal>dumpdev</literal> variable in
<filename>/etc/rc.conf</filename>. Typically you want to specify one of
the swap devices specified in <filename>/etc/fstab</filename>.
Dumps to non-swap devices, tapes for example,
are currently not supported. Config your kernel using
<command>config -g</command>. See <link linkend="kernelconfig">Kernel
Configuration</link> for
details on configuring the FreeBSD kernel.</para>
the swap devices specified in <filename>/etc/fstab</filename>. Dumps to
non-swap devices, tapes for example, are currently not supported. Config
your kernel using <command>config -g</command>. See <link
linkend="kernelconfig">Kernel Configuration</link> for details on
configuring the FreeBSD kernel.</para>
<para>Use the &man.dumpon.8; command to tell the kernel
where to dump to (note that this will have to be done after
configuring the partition in question as swap space via
&man.swapon.8;). This is normally arranged via
<filename>/etc/rc.conf</filename> and <filename>/etc/rc</filename>.
Alternatively, you can hard-code the dump device via the <literal>dump</literal>
clause in the <literal>config</literal> line of your kernel config file. This is
deprecated and should be used only if you want a crash dump from a
kernel that crashes during booting.</para>
<para>Use the &man.dumpon.8; command to tell the kernel where to dump to
(note that this will have to be done after configuring the partition in
question as swap space via &man.swapon.8;). This is normally arranged
via <filename>/etc/rc.conf</filename> and <filename>/etc/rc</filename>.
Alternatively, you can hard-code the dump device via the
<literal>dump</literal> clause in the <literal>config</literal> line of
your kernel config file. This is deprecated and should be used only if
you want a crash dump from a kernel that crashes during booting.</para>
<note>
<para>In the following, the term <command>kgdb</command> refers to
<command>gdb</command> run in &ldquo;kernel debug mode&rdquo;. This can be
accomplished by either starting the <command>gdb</command> with
the option <option>-k</option>, or by linking and starting it
under the name <command>kgdb</command>. This is not being done by
default, however, and the idea is basically deprecated since the
GNU folks do not like their tools to behave differently when
called by another name. This feature may well be discontinued in
further releases.</para>
<command>gdb</command> run in &ldquo;kernel debug mode&rdquo;. This
can be accomplished by either starting the <command>gdb</command> with
the option <option>-k</option>, or by linking and starting it under
the name <command>kgdb</command>. This is not being done by default,
however, and the idea is basically deprecated since the GNU folks do
not like their tools to behave differently when called by another
name. This feature may well be discontinued in further
releases.</para>
</note>
<para>When the kernel has been built make a copy of it, say
<filename>kernel.debug</filename>, and then run <command>strip
-d</command> on the original. Install the original as normal. You
may also install the unstripped kernel, but symbol table lookup time
for some programs will drastically increase, and since the whole
kernel is loaded entirely at boot time and cannot be swapped out
later, several megabytes of physical memory will be wasted.</para>
may also install the unstripped kernel, but symbol table lookup time for
some programs will drastically increase, and since the whole kernel is
loaded entirely at boot time and cannot be swapped out later, several
megabytes of physical memory will be wasted.</para>
<para>If you are testing a new kernel, for example by typing the new
kernel's name at the boot prompt, but need to boot a different one
in order to get your system up and running again, boot it only into
single user state using the <option>-s</option> flag at the boot
prompt, and then perform the following steps:</para>
kernel's name at the boot prompt, but need to boot a different one in
order to get your system up and running again, boot it only into single
user state using the <option>-s</option> flag at the boot prompt, and
then perform the following steps:</para>
<screen>&prompt.root; <userinput>fsck -p</userinput>
&prompt.root; <userinput>mount -a -t ufs</userinput> # so your file system for /var/crash is writable
&prompt.root; <userinput>savecore -N /kernel.panicked /var/crash</userinput>
&prompt.root; <userinput>exit</userinput> # ...to multi-user</screen>
<para>This instructs &man.savecore.8; to
use another kernel for symbol name extraction. It would otherwise
default to the currently running kernel and most likely not do
anything at all since the crash dump and the kernel symbols
differ.</para>
<para>This instructs &man.savecore.8; to use another kernel for symbol
name extraction. It would otherwise default to the currently running
kernel and most likely not do anything at all since the crash dump and
the kernel symbols differ.</para>
<para>Now, after a crash dump, go to
<filename>/sys/compile/WHATEVER</filename> and run <command>kgdb</command>. From <command>kgdb</command>
do:
<filename>/sys/compile/WHATEVER</filename> and run
<command>kgdb</command>. From <command>kgdb</command> do:
<screen><userinput>symbol-file kernel.debug</userinput>
<userinput>exec-file /var/crash/kernel.0</userinput>
<userinput>core-file /var/crash/vmcore.0</userinput></screen>
and voila, you can debug the crash dump using the kernel sources just
like you can for any other program.</para>
and voila, you can debug the crash dump using the
kernel sources just like you can for any other program.</para>
<para>Here is a script log of a <command>kgdb</command>
session illustrating the procedure. Long lines have been folded to
improve readability, and the lines are numbered for reference.
Despite this, it is a real-world error trace taken during the
development of the pcvt console driver.</para>
<para>Here is a script log of a <command>kgdb</command> session
illustrating the procedure. Long lines have been folded to improve
readability, and the lines are numbered for reference. Despite this, it
is a real-world error trace taken during the development of the pcvt
console driver.</para>
<screen> 1:Script started on Fri Dec 30 23:15:22 1994
2:&prompt.root; <userinput>cd /sys/compile/URIAH</userinput>
@ -172,68 +164,65 @@ Dumps to non-swap devices, tapes for example,
79:
80:Script done on Fri Dec 30 23:18:04 1994</screen>
<para>Comments to the above script:</para>
<variablelist>
<varlistentry><term>line 6:</term>
<listitem>
<para>This is a dump taken from within DDB (see below), hence
the panic comment &ldquo;because you said to!&rdquo;, and a rather
long stack trace; the initial reason for going into DDB has
been a page fault trap though.</para>
<varlistentry>
<term>line 6:</term>
<listitem>
<para>This is a dump taken from within DDB (see below), hence the
panic comment &ldquo;because you said to!&rdquo;, and a rather
long stack trace; the initial reason for going into DDB has been a
page fault trap though.</para>
</listitem>
</varlistentry>
<varlistentry><term>line 20:</term>
<varlistentry>
<term>line 20:</term>
<listitem>
<para>This is the location of function
<function>trap()</function> in the stack trace.</para>
<para>This is the location of function <function>trap()</function>
in the stack trace.</para>
</listitem>
</varlistentry>
<varlistentry><term>line 36:</term>
<varlistentry>
<term>line 36:</term>
<listitem>
<para>Force usage of a new stack frame; this is no longer
necessary now. The stack frames are supposed to point to
the right locations now, even in case of a trap. (I do not
have a new core dump handy &lt;g&gt;, my kernel has not
panicked for a rather long time.) From looking at the code
in source line 403, there is a high probability that either
the pointer access for &ldquo;tp&rdquo; was messed up, or the array
access was out of bounds.</para>
<para>Force usage of a new stack frame; this is no longer necessary
now. The stack frames are supposed to point to the right
locations now, even in case of a trap. (I do not have a new core
dump handy &lt;g&gt;, my kernel has not panicked for a rather long
time.) From looking at the code in source line 403, there is a
high probability that either the pointer access for
&ldquo;tp&rdquo; was messed up, or the array access was out of
bounds.</para>
</listitem>
</varlistentry>
<varlistentry><term>line 52:</term>
<varlistentry>
<term>line 52:</term>
<listitem>
<para>The pointer looks suspicious, but happens to be a valid
address.</para>
</listitem>
</varlistentry>
<varlistentry><term>line 56:</term>
<varlistentry>
<term>line 56:</term>
<listitem>
<para>However, it obviously points to garbage, so we have
found our error! (For those unfamiliar with that particular
piece of code: <literal>tp-&gt;t_line</literal>
refers to the line discipline of the console device here,
which must be a rather small integer number.)</para>
<para>However, it obviously points to garbage, so we have found our
error! (For those unfamiliar with that particular piece of code:
<literal>tp-&gt;t_line</literal> refers to the line discipline of
the console device here, which must be a rather small integer
number.)</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1>
@ -244,10 +233,8 @@ Dumps to non-swap devices, tapes for example,
option to the <command>ddd</command> command line you would use
normally. For example;</para>
<screen>&prompt.root; <userinput>ddd -k /var/crash/kernel.0 /var/crash/vmcore.0</userinput></screen>
<para>You should then be able to go about looking at the crash dump using
<command>ddd</command>'d graphical interface.</para>
</sect1>
@ -255,124 +242,115 @@ Dumps to non-swap devices, tapes for example,
<sect1>
<title>Post-mortem Analysis of a Dump</title>
<para>What do you do if a kernel dumped core but you did not expect
it, and it is therefore not compiled using <command>config
-g</command>? Not everything is lost here. Do not panic!</para>
<para>What do you do if a kernel dumped core but you did not expect it,
and it is therefore not compiled using <command>config -g</command>? Not
everything is lost here. Do not panic!</para>
<para>Of course, you still need to enable crash dumps. See above on
the options you have to specify in order to do this.</para>
<para>Of course, you still need to enable crash dumps. See above on the
options you have to specify in order to do this.</para>
<para>Go to your kernel compile directory, and edit the line
containing <literal>COPTFLAGS?=-O</literal>. Add the
<option>-g</option> option there (but <emphasis>do not</emphasis>
change anything on the level of optimization). If you do already
know roughly the probable location of the failing piece of code
(e.g., the <devicename>pcvt</devicename> driver in the example
above), remove all the object files for this code. Rebuild the
kernel. Due to the time stamp change on the Makefile, there will be
some other object files rebuild, for example
<para>Go to your kernel compile directory, and edit the line containing
<literal>COPTFLAGS?=-O</literal>. Add the <option>-g</option> option
there (but <emphasis>do not</emphasis> change anything on the level of
optimization). If you do already know roughly the probable location of
the failing piece of code (e.g., the <devicename>pcvt</devicename>
driver in the example above), remove all the object files for this code.
Rebuild the kernel. Due to the time stamp change on the Makefile, there
will be some other object files rebuild, for example
<filename>trap.o</filename>. With a bit of luck, the added
<option>-g</option> option will not change anything for the
generated code, so you will finally get a new kernel with similar
code to the faulting one but some debugging symbols. You should at
least verify the old and new sizes with the
&man.size.1; command. If there is a mismatch, you
probably need to give up here.</para>
<option>-g</option> option will not change anything for the generated
code, so you will finally get a new kernel with similar code to the
faulting one but some debugging symbols. You should at least verify the
old and new sizes with the
&man.size.1; command. If there is a mismatch, you probably need to
give up here.</para>
<para>Go and examine the dump as described above. The debugging
symbols might be incomplete for some places, as can be seen in the
stack trace in the example above where some functions are displayed
without line numbers and argument lists. If you need more debugging
symbols, remove the appropriate object files and repeat the
<command>kgdb</command> session until you know
enough.</para>
<para>All this is not guaranteed to work, but it will do it fine in
most cases.</para>
<para>Go and examine the dump as described above. The debugging symbols
might be incomplete for some places, as can be seen in the stack trace
in the example above where some functions are displayed without line
numbers and argument lists. If you need more debugging symbols, remove
the appropriate object files and repeat the <command>kgdb</command>
session until you know enough.</para>
<para>All this is not guaranteed to work, but it will do it fine in most
cases.</para>
</sect1>
<sect1>
<title>On-line Kernel Debugging Using DDB</title>
<para>While <command>kgdb</command> as an offline debugger
provides a very high level of user interface, there are some things
it cannot do. The most important ones being breakpointing and
single-stepping kernel code.</para>
<para>While <command>kgdb</command> as an offline debugger provides a very
high level of user interface, there are some things it cannot do. The
most important ones being breakpointing and single-stepping kernel
code.</para>
<para>If you need to do low-level debugging on your kernel, there is
an on-line debugger available called DDB. It allows to setting
<para>If you need to do low-level debugging on your kernel, there is an
on-line debugger available called DDB. It allows to setting
breakpoints, single-steping kernel functions, examining and changing
kernel variables, etc. However, it cannot access kernel source
files, and only has access to the global and static symbols, not to
the full debug information like <command>kgdb</command>.</para>
kernel variables, etc. However, it cannot access kernel source files,
and only has access to the global and static symbols, not to the full
debug information like <command>kgdb</command>.</para>
<para>To configure your kernel to include DDB, add the option line
<programlisting>
options DDB</programlisting> to your config file, and rebuild. (See <link
linkend="kernelconfig">Kernel Configuration</link> for details on configuring the
FreeBSD kernel.</para>
options DDB</programlisting>
to your config file, and rebuild. (See <link
linkend="kernelconfig">Kernel Configuration</link> for details on
configuring the FreeBSD kernel.</para>
<note>
<para>Note that if you have an older version of the boot blocks,
your debugger symbols might not be loaded at all. Update the boot
blocks; the recent ones load the DDB symbols
automagically.)</para>
<para>Note that if you have an older version of the boot blocks, your
debugger symbols might not be loaded at all. Update the boot blocks;
the recent ones load the DDB symbols automagically.)</para>
</note>
<para>Once your DDB kernel is running, there are several ways to enter
DDB. The first, and earliest way is to type the boot flag
<option>-d</option> right at the boot prompt. The kernel will start
up in debug mode and enter DDB prior to any device probing. Hence
you can even debug the device probe/attach functions.</para>
<option>-d</option> right at the boot prompt. The kernel will start up
in debug mode and enter DDB prior to any device probing. Hence you can
even debug the device probe/attach functions.</para>
<para>The second scenario is a hot-key on the keyboard, usually
Ctrl-Alt-ESC. For syscons, this can be remapped; some of the
distributed maps do this, so watch out. There is an option available
for serial consoles that allows the use of a serial line BREAK on
the console line to enter DDB (<literal>options
BREAK_TO_DEBUGGER</literal> in the kernel config file). It is
not the default since there are a lot of crappy serial adapters
around that gratuitously generate a BREAK condition, for example
when pulling the cable.</para>
for serial consoles that allows the use of a serial line BREAK on the
console line to enter DDB (<literal>options BREAK_TO_DEBUGGER</literal>
in the kernel config file). It is not the default since there are a lot
of crappy serial adapters around that gratuitously generate a BREAK
condition, for example when pulling the cable.</para>
<para>The third way is that any panic condition will branch to DDB if
the kernel is configured to use it. For this reason, it is not
wise to configure a kernel with DDB for a machine running
unattended.</para>
<para>The DDB commands roughly resemble some <command>gdb</command> commands. The first thing you probably
need to do is to set a breakpoint:</para>
<para>The third way is that any panic condition will branch to DDB if the
kernel is configured to use it. For this reason, it is not wise to
configure a kernel with DDB for a machine running unattended.</para>
<para>The DDB commands roughly resemble some <command>gdb</command>
commands. The first thing you probably need to do is to set a
breakpoint:</para>
<screen><userinput>b function-name</userinput>
<userinput>b address</userinput></screen>
<para>Numbers are taken hexadecimal by default, but to make them distinct
from symbol names; hexadecimal numbers starting with the letters
<literal>a-f</literal> need to be preceded with <literal>0x</literal>
(this is optional for other numbers). Simple expressions are allowed,
for example: <literal>function-name + 0x103</literal>.</para>
<para>Numbers are taken hexadecimal by default, but to make them
distinct from symbol names; hexadecimal numbers starting with the
letters <literal>a-f</literal> need to be preceded with
<literal>0x</literal> (this is optional for other numbers). Simple
expressions are allowed, for example: <literal>function-name +
0x103</literal>.</para>
<para>To continue the operation of an interrupted kernel, simply type:</para>
<para>To continue the operation of an interrupted kernel, simply
type:</para>
<screen><userinput>c</userinput></screen>
<para>To get a stack trace, use:</para>
<screen><userinput>trace</userinput></screen>
<note>
<para>Note that when entering DDB via a hot-key, the kernel is
currently servicing an interrupt, so the stack trace might be not
of much use for you.</para>
<para>Note that when entering DDB via a hot-key, the kernel is currently
servicing an interrupt, so the stack trace might be not of much use
for you.</para>
</note>
<para>If you want to remove a breakpoint, use</para>
@ -381,178 +359,143 @@ options DDB</programlisting> to your config file, and rebuild. (See <link
<screen><userinput>del</userinput>
<userinput>del address-expression</userinput></screen>
<para>The first form will be accepted immediately after
a breakpoint hit, and deletes the current breakpoint. The second
form can remove any breakpoint, but you need to specify the exact
address; this can be obtained from:</para>
<para>The first form will be accepted immediately after a breakpoint hit,
and deletes the current breakpoint. The second form can remove any
breakpoint, but you need to specify the exact address; this can be
obtained from:</para>
<screen><userinput>show b</userinput></screen>
<para>To single-step the kernel, try:</para>
<screen><userinput>s</userinput></screen>
<para>This will step into functions, but you can make
DDB trace them until the matching return statement is reached by:</para>
<para>This will step into functions, but you can make DDB trace them until
the matching return statement is reached by:</para>
<screen><userinput>n</userinput></screen>
<note>
<para>This is different from <command>gdb</command>'s <command>next</command>
statement; it is like <command>gdb</command>'s <command>finish</command>.</para>
<para>This is different from <command>gdb</command>'s
<command>next</command> statement; it is like <command>gdb</command>'s
<command>finish</command>.</para>
</note>
<para>To examine data from memory, use (for example):
<screen><userinput>x/wx 0xf0133fe0,40</userinput>
<userinput>x/hd db_symtab_space</userinput>
<userinput>x/bc termbuf,10</userinput>
<userinput>x/s stringbuf</userinput></screen>
for word/halfword/byte access, and
hexadecimal/decimal/character/ string display. The number after the
comma is the object count. To display the next 0x10 items, simply
use:</para>
for word/halfword/byte access, and hexadecimal/decimal/character/ string
display. The number after the comma is the object count. To display
the next 0x10 items, simply use:</para>
<screen><userinput>x ,10</userinput></screen>
<para>Similarly, use
<screen><userinput>x/ia foofunc,10</userinput></screen>
to disassemble the first 0x10 instructions of
<function>foofunc</function>, and display them along with
their offset from the beginning of <function>foofunc</function>.</para>
<function>foofunc</function>, and display them along with their offset
from the beginning of <function>foofunc</function>.</para>
<para>To modify memory, use the write command:</para>
<screen><userinput>w/b termbuf 0xa 0xb 0</userinput>
<userinput>w/w 0xf0010030 0 0</userinput></screen>
<para>The command modifier
(<literal>b</literal>/<literal>h</literal>/<literal>w</literal>) specifies the size of the data to be
written, the first following expression is the address to write to
and the remainder is interpreted as data to write to successive
memory locations.</para>
(<literal>b</literal>/<literal>h</literal>/<literal>w</literal>)
specifies the size of the data to be written, the first following
expression is the address to write to and the remainder is interpreted
as data to write to successive memory locations.</para>
<para>If you need to know the current registers, use:</para>
<screen><userinput>show reg</userinput></screen>
<para>Alternatively, you can display a single register
value by e.g.
<para>Alternatively, you can display a single register value by e.g.
<screen><userinput>p $eax</userinput></screen>
and modify it by:</para>
<screen><userinput>set $eax new-value</userinput></screen>
<para>Should you need to call some kernel functions from DDB, simply
say:</para>
<screen><userinput>call func(arg1, arg2, ...)</userinput></screen>
<para>The return value will be printed.</para>
<para>For a &man.ps.1; style summary of all running
processes, use:</para>
<para>For a &man.ps.1; style summary of all running processes, use:</para>
<screen><userinput>ps</userinput></screen>
<para>Now you have now examined why your kernel failed, and you wish
to reboot. Remember that, depending on the severity of previous
malfunctioning, not all parts of the kernel might still be working
as expected. Perform one of the following actions to shut down and
reboot your system:</para>
<para>Now you have now examined why your kernel failed, and you wish to
reboot. Remember that, depending on the severity of previous
malfunctioning, not all parts of the kernel might still be working as
expected. Perform one of the following actions to shut down and reboot
your system:</para>
<screen><userinput>call diediedie()</userinput></screen>
<para>This will cause your kernel to dump core and reboot, so you can
later analyze the core on a higher level with kgdb. This command
usually must be followed by another <command>continue</command> statement. There is now an alias for
this: <command>panic</command>.</para>
usually must be followed by another <command>continue</command>
statement. There is now an alias for this:
<command>panic</command>.</para>
<screen><userinput>call boot(0)</userinput></screen>
<para>Which might be a good way to cleanly shut down the
running system, <function>sync()</function> all disks, and finally
reboot. As long as the disk and file system interfaces of the
kernel are not damaged, this might be a good way for an almost clean
shutdown.</para>
<para>Which might be a good way to cleanly shut down the running system,
<function>sync()</function> all disks, and finally reboot. As long as
the disk and file system interfaces of the kernel are not damaged, this
might be a good way for an almost clean shutdown.</para>
<screen><userinput>call cpu_reset()</userinput></screen>
<para>is the final way out of disaster and almost the
same as hitting the Big Red Button.</para>
<para>is the final way out of disaster and almost the same as hitting the
Big Red Button.</para>
<para>If you need a short command summary, simply type:</para>
<screen><userinput>help</userinput></screen>
<para>However, it is highly recommended to have a
printed copy of the &man.ddb.4; manual page
ready for a debugging session. Remember that it is hard to read the
on-line manual while single-stepping the kernel.</para>
<para>However, it is highly recommended to have a printed copy of the
&man.ddb.4; manual page ready for a debugging
session. Remember that it is hard to read the on-line manual while
single-stepping the kernel.</para>
</sect1>
<sect1>
<title>On-line Kernel Debugging Using Remote GDB</title>
<para>This feature has been supported since FreeBSD 2.2, and it's
actually a very neat one.</para>
<para>This feature has been supported since FreeBSD 2.2, and it's actually
a very neat one.</para>
<para>GDB has already supported <emphasis>remote debugging</emphasis>
for a long time. This is done using a very simple protocol along a
serial line. Unlike the other methods described above, you will
need two machines for doing this. One is the host providing the
debugging environment, including all the sources, and a copy of the
kernel binary with all the symbols in it, and the other one is the
target machine that simply runs a similar copy of the very same
kernel (but stripped of the debugging information).</para>
<para>GDB has already supported <emphasis>remote debugging</emphasis> for
a long time. This is done using a very simple protocol along a serial
line. Unlike the other methods described above, you will need two
machines for doing this. One is the host providing the debugging
environment, including all the sources, and a copy of the kernel binary
with all the symbols in it, and the other one is the target machine that
simply runs a similar copy of the very same kernel (but stripped of the
debugging information).</para>
<para>You should configure the kernel in question with <command>config
-g</command>, include <option>DDB</option> into the
configuration, and compile it as usual. This gives a large blurb of
a binary, due to the debugging information. Copy this kernel to the
target machine, strip the debugging symbols off with <command>strip
-x</command>, and boot it using the <option>-d</option> boot
option. Connect the first serial line of the target machine to any
serial line of the debugging host. Now, on the debugging machine,
go to the compile directory of the target kernel, and start gdb:</para>
-g</command>, include <option>DDB</option> into the configuration, and
compile it as usual. This gives a large blurb of a binary, due to the
debugging information. Copy this kernel to the target machine, strip
the debugging symbols off with <command>strip -x</command>, and boot it
using the <option>-d</option> boot option. Connect the first serial
line of the target machine to any serial line of the debugging host.
Now, on the debugging machine, go to the compile directory of the target
kernel, and start gdb:</para>
<screen>&prompt.user; <userinput>gdb -k kernel</userinput>
GDB is free software and you are welcome to distribute copies of it
@ -562,94 +505,77 @@ GDB 4.16 (i386-unknown-freebsd),
Copyright 1996 Free Software Foundation, Inc...
<prompt>(kgdb)</prompt> </screen>
<para>Initialize the remote debugging session (assuming the first
serial port is being used) by:</para>
<para>Initialize the remote debugging session (assuming the first serial
port is being used) by:</para>
<screen><prompt>(kgdb)</prompt> <userinput>target remote /dev/cuaa0</userinput></screen>
<para>Now, on the target host (the one that entered DDB right before
even starting the device probe), type:</para>
<para>Now, on the target host (the one that entered DDB right before even
starting the device probe), type:</para>
<screen>Debugger("Boot flags requested debugger")
Stopped at Debugger+0x35: movb $0, edata+0x51bc
<prompt>db&gt;</prompt> <userinput>gdb</userinput></screen>
<para>DDB will respond with:</para>
<screen>Next trap will enter GDB remote protocol mode</screen>
<para>Every time you type <command>gdb</command>, the mode will be toggled between
remote GDB and local DDB. In order to force a next trap
immediately, simply type <command>s</command> (step). Your hosting GDB will now
gain control over the target kernel:</para>
<para>Every time you type <command>gdb</command>, the mode will be toggled
between remote GDB and local DDB. In order to force a next trap
immediately, simply type <command>s</command> (step). Your hosting GDB
will now gain control over the target kernel:</para>
<screen>Remote debugging using /dev/cuaa0
Debugger (msg=0xf01b0383 "Boot flags requested debugger")
at ../../i386/i386/db_interface.c:257
<prompt>(kgdb)</prompt></screen>
<para>You can use this session almost as any other GDB session, including
full access to the source, running it in gud-mode inside an Emacs window
(which gives you an automatic source code display in another Emacs
window) etc.</para>
<para>You can use this session almost as any other GDB session,
including full access to the source, running it in gud-mode inside
an Emacs window (which gives you an automatic source code display in
another Emacs window) etc.</para>
<para>Remote GDB can also be used to debug LKMs. First build the LKM
with debugging symbols:</para>
<para>Remote GDB can also be used to debug LKMs. First build the LKM with
debugging symbols:</para>
<screen>&prompt.root; <userinput>cd /usr/src/lkm/linux</userinput>
&prompt.root; <userinput>make clean; make COPTS=-g</userinput></screen>
<para>Then install this version of the module on the target machine,
load it and use <command>modstat</command> to find out
where it was loaded:</para>
<para>Then install this version of the module on the target machine, load
it and use <command>modstat</command> to find out where it was
loaded:</para>
<screen>&prompt.root; <userinput>linux</userinput>
&prompt.root; <userinput>modstat</userinput>
Type Id Off Loadaddr Size Info Rev Module Name
EXEC 0 4 f5109000 001c f510f010 1 linux_mod</screen>
<para>Take the load address of the module and add 0x20 (probably to
account for the a.out header). This is the address that the module
code was relocated to. Use the <command>add-symbol-file</command> command in GDB to tell the
debugger about the module:</para>
account for the a.out header). This is the address that the module code
was relocated to. Use the <command>add-symbol-file</command> command in
GDB to tell the debugger about the module:</para>
<screen><prompt>(kgdb)</prompt> <userinput>add-symbol-file /usr/src/lkm/linux/linux_mod.o 0xf5109020</userinput>
add symbol table from file "/usr/src/lkm/linux/linux_mod.o" at
text_addr = 0xf5109020? (y or n) <userinput>y</userinput>
<prompt>(kgdb)</prompt></screen>
<para>You now have access to all the symbols in the LKM.</para>
</sect1>
<sect1>
<title>Debugging a Console Driver</title>
<para>Since you need a console driver to run DDB on, things are more
complicated if the console driver itself is failing. You might
remember the use of a serial console (either with modified boot
blocks, or by specifying <option>-h</option> at the <prompt>Boot:</prompt> prompt), and hook up a standard terminal
onto your first serial port. DDB works on any configured console
driver, of course also on a serial console.</para>
complicated if the console driver itself is failing. You might remember
the use of a serial console (either with modified boot blocks, or by
specifying <option>-h</option> at the <prompt>Boot:</prompt> prompt),
and hook up a standard terminal onto your first serial port. DDB works
on any configured console driver, of course also on a serial
console.</para>
</sect1>
</chapter>
</chapter>
<!--
Local Variables:

175
en_US.ISO8859-1/books/handbook/kernelopts/chapter.sgml
View file

@ -1,53 +1,50 @@
<chapter id="kernelopts">
<chapter id="kernelopts">
<title>Adding New Kernel Configuration Options</title>
<para><emphasis>Contributed by &a.joerg;</emphasis></para>
<note>
<para>You should be familiar with the section about <link
linkend="kernelconfig">kernel configuration</link>
before reading here.</para>
linkend="kernelconfig">kernel configuration</link> before reading
here.</para>
</note>
<sect1>
<title>What's a <emphasis>Kernel Option</emphasis>, Anyway?</title>
<para>The use of kernel options is basically described in the <link
linkend="kernelconfig-options">kernel configuration</link>
section. There's also an explanation of &ldquo;historic&rdquo; and
&ldquo;new-style&rdquo; options. The ultimate goal is to eventually turn all
the supported options in the kernel into new-style ones, so for
people who correctly did a <command>make depend</command>
in their kernel compile directory after running
&man.config.8;, the build process will automatically
pick up modified options, and only recompile those files where it is
necessary. Wiping out the old compile directory on each run of
&man.config.8; as it is still done now can then be
eliminated again.</para>
linkend="kernelconfig-options">kernel configuration</link> section.
There's also an explanation of &ldquo;historic&rdquo; and
&ldquo;new-style&rdquo; options. The ultimate goal is to eventually
turn all the supported options in the kernel into new-style ones, so for
people who correctly did a <command>make depend</command> in their
kernel compile directory after running
&man.config.8;, the build process will automatically pick up modified
options, and only recompile those files where it is necessary. Wiping
out the old compile directory on each run of &man.config.8; as it is
still done now can then be eliminated again.</para>
<para>Basically, a kernel option is nothing else than the definition
of a C preprocessor macro for the kernel compilation process. To
make the build truly optional, the corresponding part of the kernel
source (or kernel <filename>.h</filename> file) must be written with
the option concept in mind, i.e. the default must have been made
overridable by the config option. This is usually done with
something like:</para>
<para>Basically, a kernel option is nothing else than the definition of a
C preprocessor macro for the kernel compilation process. To make the
build truly optional, the corresponding part of the kernel source (or
kernel <filename>.h</filename> file) must be written with the option
concept in mind, i.e. the default must have been made overridable by the
config option. This is usually done with something like:</para>
<programlisting>
#ifndef THIS_OPTION
#define THIS_OPTION (some_default_value)
#endif /* THIS_OPTION */</programlisting>
<para>This way, an administrator mentioning another value for the
option in his config file will take the default out of effect, and
replace it with his new value. Clearly, the new value will be
substituted into the source code during the preprocessor run, so it
must be a valid C expression in whatever context the default value
would have been used.</para>
<para>This way, an administrator mentioning another value for the option
in his config file will take the default out of effect, and replace it
with his new value. Clearly, the new value will be substituted into the
source code during the preprocessor run, so it must be a valid C
expression in whatever context the default value would have been
used.</para>
<para>It is also possible to create value-less options that simply
enable or disable a particular piece of code by embracing it
in</para>
<para>It is also possible to create value-less options that simply enable
or disable a particular piece of code by embracing it in</para>
<programlisting>
#ifdef THAT_OPTION
@ -56,15 +53,14 @@
#endif</programlisting>
<para>Simply mentioning <literal>THAT_OPTION</literal> in the config
file (with or without any value) will then turn on the corresponding
piece of code.</para>
<para>Simply mentioning <literal>THAT_OPTION</literal> in the config file
(with or without any value) will then turn on the corresponding piece of
code.</para>
<para>People familiar with the C language will immediately recognize
that everything could be counted as a &ldquo;config option&rdquo; where there
is at least a single <literal>#ifdef</literal>
referencing it... However, it's unlikely that many people would
put</para>
<para>People familiar with the C language will immediately recognize that
everything could be counted as a &ldquo;config option&rdquo; where there
is at least a single <literal>#ifdef</literal> referencing it...
However, it's unlikely that many people would put</para>
<programlisting>
options notyet,notdef</programlisting>
@ -72,38 +68,40 @@ options notyet,notdef</programlisting>
<para>in their config file, and then wonder why the kernel compilation
falls over. <!-- smiley -->:-)</para>
<para>Clearly, using arbitrary names for the options makes it very
hard to track their usage throughout the kernel source tree. That
is the rationale behind the <emphasis>new-style</emphasis> option
scheme, where each option goes into a separate
<filename>.h</filename> file in the kernel compile directory, which
is by convention named
<para>Clearly, using arbitrary names for the options makes it very hard to
track their usage throughout the kernel source tree. That is the
rationale behind the <emphasis>new-style</emphasis> option scheme, where
each option goes into a separate <filename>.h</filename> file in the
kernel compile directory, which is by convention named
<filename>opt_<replaceable>foo</replaceable>.h</filename>. This way,
the usual Makefile dependencies could be applied, and <command>make</command> can determine what needs to be recompiled
once an option has been changed.</para>
the usual Makefile dependencies could be applied, and
<command>make</command> can determine what needs to be recompiled once
an option has been changed.</para>
<para>The old-style option mechanism still has one advantage for local
options or maybe experimental options that have a short anticipated
lifetime: since it is easy to add a new <literal>#ifdef</literal> to the kernel source, this has already
made it a kernel config option. In this case, the administrator
using such an option is responsible himself for knowing about its
implications (and maybe manually forcing the recompilation of parts
of his kernel). Once the transition of all supported options has
been done, &man.config.8; will warn whenever an
unsupported option appears in the config file, but it will
nevertheless include it into the kernel Makefile.</para>
lifetime: since it is easy to add a new <literal>#ifdef</literal> to the
kernel source, this has already made it a kernel config option. In this
case, the administrator using such an option is responsible himself for
knowing about its implications (and maybe manually forcing the
recompilation of parts of his kernel). Once the transition of all
supported options has been done, &man.config.8; will warn whenever an
unsupported option appears in the config file, but it will nevertheless
include it into the kernel Makefile.</para>
</sect1>
<sect1>
<title>Now What Do I Have to Do for it?</title>
<para>First, edit <filename>sys/conf/options</filename> (or
<filename>sys/i386/conf/options.<replaceable>&lt;arch&gt;</replaceable></filename>, e. g. <filename>sys/i386/conf/options.i386</filename>), and select an <filename>opt_<replaceable>foo</replaceable>.h</filename> file where your new option would best go into.</para>
<filename>sys/i386/conf/options.<replaceable>&lt;arch&gt;</replaceable></filename>,
e. g. <filename>sys/i386/conf/options.i386</filename>), and select an
<filename>opt_<replaceable>foo</replaceable>.h</filename> file where
your new option would best go into.</para>
<para>If there is already something that comes close to the purpose of
the new option, pick this. For example, options modifying the
overall behaviour of the SCSI subsystem can go into
<para>If there is already something that comes close to the purpose of the
new option, pick this. For example, options modifying the overall
behaviour of the SCSI subsystem can go into
<filename>opt_scsi.h</filename>. By default, simply mentioning an
option in the appropriate option file, say <literal>FOO</literal>,
implies its value will go into the corresponding file
@ -114,51 +112,38 @@ options notyet,notdef</programlisting>
<filename>opt_<replaceable>foo</replaceable>.h</filename> already
available for the intended new option, invent a new name. Make it
meaningful, and comment the new section in the
<filename>options[<replaceable>.&lt;arch&gt;</replaceable>]</filename> file. &man.config.8; will automagically pick up the change, and create that file next time it is run. Most options should go in a header file by themselves..</para>
<filename>options[<replaceable>.&lt;arch&gt;</replaceable>]</filename>
file. &man.config.8; will automagically pick up the change, and create
that file next time it is run. Most options should go in a header file
by themselves..</para>
<para>Packing too many options into a single
<filename>opt_<replaceable>foo</replaceable>.h</filename> will cause
too many kernel files to be rebuilt when one of the options has been
changed in the config file.</para>
<filename>opt_<replaceable>foo</replaceable>.h</filename> will cause too
many kernel files to be rebuilt when one of the options has been changed
in the config file.</para>
<para>Finally, find out which kernel files depend on the new option.
Unless you have just invented your option, and it does not exist
anywhere yet,
anywhere yet, <screen>&prompt.user; <userinput>find /usr/src/sys -name
type f | xargs fgrep NEW_OPTION</userinput></screen> is your friend
in finding them. Go and edit all those files, and add <programlisting>
#include "opt_foo.h"</programlisting> <emphasis>on top</emphasis>,
before all the <literal>#include &lt;xxx.h&gt;</literal> stuff. This
sequence is most important as the options could override defaults from
the regular include files, if the defaults are of the form
<programlisting> #ifndef NEW_OPTION #define NEW_OPTION (something)
#endif</programlisting> in the regular header.</para>
<screen>&prompt.user; <userinput>find /usr/src/sys -name type f | xargs fgrep NEW_OPTION</userinput></screen>
is your friend in finding them. Go and edit all those files,
and add
<programlisting>
#include "opt_foo.h"</programlisting>
<emphasis>on top</emphasis>, before all the <literal>#include &lt;xxx.h&gt;</literal> stuff. This sequence
is most important as the options could override defaults from the
regular include files, if the defaults are of the form
<programlisting>
#ifndef NEW_OPTION
#define NEW_OPTION (something)
#endif</programlisting>
in the regular header.</para>
<para>Adding an option that overrides something in a system header
file (i.e., a file sitting in
<filename>/usr/include/sys/</filename>) is almost always a mistake.
<para>Adding an option that overrides something in a system header file
(i.e., a file sitting in <filename>/usr/include/sys/</filename>) is
almost always a mistake.
<filename>opt_<replaceable>foo</replaceable>.h</filename> cannot be
included into those files since it would break the headers more
seriously, but if it is not included, then places that include it
may get an inconsistent value for the option. Yes, there are
precedents for this right now, but that does not make them more
correct.</para>
seriously, but if it is not included, then places that include it may
get an inconsistent value for the option. Yes, there are precedents for
this right now, but that does not make them more correct.</para>
</sect1>
</chapter>
</chapter>
<!--
Local Variables:

221
en_US.ISO8859-1/books/handbook/l10n/chapter.sgml
View file

@ -1,7 +1,6 @@
<chapter id="l10n">
<chapter id="l10n">
<title>Localization</title>
<sect1 id="russian">
<title>Russian Language (KOI8-R encoding)</title>
@ -12,20 +11,18 @@
URL="http://www.nagual.pp.ru/~ache/koi8.html">KOI8-R References
(Russian Net Character Set)</ulink>.</para>
<sect2 id="russian-console">
<title>Console Setup</title>
<procedure>
<step>
<para>Add following line to your kernel configuration file:
<programlisting>
options "SC_MOUSE_CHAR=0x03"</programlisting> to move character
codes used for mouse cursor off KOI8-R pseudographics
range.</para>
options "SC_MOUSE_CHAR=0x03"</programlisting>
to move character codes used for mouse cursor off KOI8-R
pseudographics range.</para>
</step>
<step>
@ -42,35 +39,31 @@ font8x8=cp866-8x8</programlisting>
<note>
<para>^[ means that real ESC character must be entered into
<filename>/etc/rc.conf</filename>, not just ^[
string.</para>
<filename>/etc/rc.conf</filename>, not just ^[ string.</para>
</note>
<para>This tuning means KOI8-R keyboard with Alternative
screen font mapped to KOI8-R encoding to preserve
pseudographics, <literal>Gray Delete</literal>
key remapped to match Russian &man.termcap.5; entry for FreeBSD
console.</para>
<para>This tuning means KOI8-R keyboard with Alternative screen font
mapped to KOI8-R encoding to preserve pseudographics,
<literal>Gray Delete</literal> key remapped to match Russian
&man.termcap.5; entry for
FreeBSD console.</para>
<para>RUS/LAT switch will be <literal>CapsLock</literal>. Old CapsLock function still
available via <literal>Shift+CapsLock</literal>.
CapsLock LED will indicate RUS mode, not CapsLock
mode.</para>
<para>RUS/LAT switch will be <literal>CapsLock</literal>. Old
CapsLock function still available via
<literal>Shift+CapsLock</literal>. CapsLock LED will indicate RUS
mode, not CapsLock mode.</para>
</step>
<step>
<para>For each <literal>ttyv?</literal> entry in
<filename>/etc/ttys</filename> change terminal type from
<literal>cons25</literal> to <literal>cons25r</literal>, i.e. each entry should looks
like:</para>
<literal>cons25</literal> to <literal>cons25r</literal>, i.e. each
entry should looks like:</para>
<programlisting>
ttyv0 "/usr/libexec/getty Pc" cons25r on secure</programlisting>
</step>
</procedure>
</sect2>
<sect2 id="russian-locale">
@ -80,32 +73,28 @@ ttyv0 "/usr/libexec/getty Pc" cons25r on secure</programlisting>
for locale setup:</para>
<itemizedlist>
<listitem>
<para><envar>LANG</envar> for POSIX
&man.setlocale.3; family functions;</para>
<para><envar>LANG</envar> for POSIX &man.setlocale.3; family
functions;</para>
</listitem>
<listitem>
<para><envar>MM_CHARSET</envar> for applications MIME
chararter set.</para>
<para><envar>MM_CHARSET</envar> for applications MIME chararter
set.</para>
</listitem>
</itemizedlist>
<para>The best way is using <filename>/etc/login.conf</filename>
<literal>russian</literal> user's login class in
&man.passwd.5; entry login class
position. See &man.login.conf.5; for
details.</para>
&man.passwd.5; entry login class position. See &man.login.conf.5;
for details.</para>
<sect3 id="russian-class">
<title>Login Class Method</title>
<para>First of all check your <filename>/etc/login.conf</filename>
have <literal>russian</literal> login class, this
entry may looks like:</para>
have <literal>russian</literal> login class, this entry may looks
like:</para>
<programlisting>
russian:Russian Users Accounts:\
@ -113,82 +102,71 @@ russian:Russian Users Accounts:\
:lang=ru_RU.KOI8-R:\
:tc=default:</programlisting>
<sect4>
<title>How to do it with &man.vipw.8;</title>
<para>If you use &man.vipw.8; for adding new
users, <filename>/etc/master.passwd</filename> entry should
looks like:</para>
<para>If you use &man.vipw.8; for adding new users,
<filename>/etc/master.passwd</filename> entry should looks
like:</para>
<programlisting>
user:password:1111:11:russian:0:0:User Name:/home/user:/bin/csh</programlisting>
</sect4>
<sect4>
<title>How to do it with &man.adduser.8;</title>
<para>If you use &man.adduser.8; for adding new
users:</para>
<itemizedlist>
<para>If you use &man.adduser.8; for adding new users:</para>
<itemizedlist>
<listitem>
<para>Set
<programlisting>
defaultclass = russian</programlisting> in
<filename>/etc/adduser.conf</filename> (you must enter
<literal>default</literal> class for all
non-Russian users in this case);</para>
defaultclass = russian</programlisting>
in <filename>/etc/adduser.conf</filename> (you must enter
<literal>default</literal> class for all non-Russian users in
this case);</para>
</listitem>
<listitem>
<para>Alternative variant will be answering <literal>russian</literal> each time when you see
<para>Alternative variant will be answering
<literal>russian</literal> each time when you see
<screen><prompt>Enter login class:</prompt> default []:</screen>
prompt from
&man.adduser.8;;</para>
prompt from &man.adduser.8;;</para>
</listitem>
<listitem>
<para>Another variant: call
<screen>&prompt.root; <userinput>adduser -class russian</userinput></screen>
for each Russian user
you want to add.</para>
for each Russian user you want to add.</para>
</listitem>
</itemizedlist>
</sect4>
<sect4>
<title>How to do it with &man.pw.8;</title>
<para>If you use &man.pw.8; for adding new users,
call it in this form:</para>
<para>If you use &man.pw.8; for adding new users, call it in this
form:</para>
<screen>&prompt.root; <userinput>pw useradd user_name -L russian</userinput></screen>
</sect4>
</sect3>
<sect3>
<title>Shell Startup Files Method</title>
<para>If you don't want to use
<link linkend="russian-class">login class method</link> for
some reasons, just set this
<link linkend="russian-env">two environment variables</link>
in the following shell startup files:</para>
<para>If you don't want to use <link linkend="russian-class">login
class method</link> for some reasons, just set this <link
linkend="russian-env">two environment variables</link> in the
following shell startup files:</para>
<itemizedlist>
<listitem>
<para><filename>/etc/profile</filename>:</para>
@ -204,18 +182,15 @@ MM_CHARSET=KOI8-R; export MM_CHARSET</programlisting>
setenv LANG ru_RU.KOI8-R
setenv MM_CHARSET KOI8-R</programlisting>
</listitem>
</itemizedlist>
<para>Alternatively you can add this instructions to</para>
<itemizedlist>
<itemizedlist>
<listitem>
<para><filename>/usr/share/skel/dot.profile</filename>:</para>
<para>(similar to <filename>/etc/profile</filename>
above);</para>
<para>(similar to <filename>/etc/profile</filename> above);</para>
</listitem>
<listitem>
@ -224,21 +199,18 @@ setenv MM_CHARSET KOI8-R</programlisting>
<para>(similar to <filename>/etc/csh.login</filename>
above).</para>
</listitem>
</itemizedlist>
</sect3>
</sect2>
<sect2 id="russian-printer">
<title>Printer Setup</title>
<para>Since most printers with Russian characters comes with
hardware code page CP866, special output filter needed for KOI8-R
-&gt; CP866 conversion. Such filter installed by default as
<filename>/usr/libexec/lpr/ru/koi2alt</filename>. So, Russian
printer <filename>/etc/printcap</filename> entry should looks
like:</para>
<para>Since most printers with Russian characters comes with hardware
code page CP866, special output filter needed for KOI8-R -&gt; CP866
conversion. Such filter installed by default as
<filename>/usr/libexec/lpr/ru/koi2alt</filename>. So, Russian printer
<filename>/etc/printcap</filename> entry should looks like:</para>
<programlisting>
lp|Russian local line printer:\
@ -246,22 +218,19 @@ lp|Russian local line printer:\
:lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs:</programlisting>
<para>See &man.printcap.5; for detailed description.</para>
</sect2>
<sect2 id="russian-msdosfs">
<title>MSDOS FS and Russian file names</title>
<para>Look at following example &man.fstab.5; entry to enable support for Russian
file names in MSDOS FS:</para>
<para>Look at following example &man.fstab.5; entry to enable support
for Russian file names in MSDOS FS:</para>
<programlisting>
/dev/sd0s1 /dos/c msdos rw,-W=koi2dos,-L=ru_RU.KOI8-R 0 0</programlisting>
<para>See
&man.mount.msdos.8; for detailed description of
<para>See &man.mount.msdos.8; for detailed description of
<option>-W</option> and <option>-L</option> options.</para>
</sect2>
<sect2 id="russian-xwindow">
@ -270,22 +239,18 @@ lp|Russian local line printer:\
<para>Step by step instructions:</para>
<procedure>
<step>
<para>Do
<link linkend="russian-locale">non-X locale setup</link>
<para>Do <link linkend="russian-locale">non-X locale setup</link>
first as described.</para>
<note>
<para><anchor id="russian-note">Russian KOI8-R locale may
not work with old XFree86 releases (lower than 3.3).
XFree86 port from
<filename>/usr/ports/x11/XFree86</filename> already have
most recent XFree86 version, so it will work, if you
install XFree86 from this port. XFree86 version shipped
with the latest FreeBSD distribution should work too
(check XFree86 version number not less than 3.3
first).</para>
<para><anchor id="russian-note">Russian KOI8-R locale may not work
with old XFree86 releases (lower than 3.3). XFree86 port from
<filename>/usr/ports/x11/XFree86</filename> already have most
recent XFree86 version, so it will work, if you install XFree86
from this port. XFree86 version shipped with the latest FreeBSD
distribution should work too (check XFree86 version number not
less than 3.3 first).</para>
</note>
</step>
@ -293,63 +258,61 @@ lp|Russian local line printer:\
<para>Go to <filename>/usr/ports/russian/X.language</filename>
directory and say
<screen>&prompt.root; <userinput>make all install</userinput></screen>
there. This port install latest
version of KOI8-R fonts. XFree86 3.3 already have some
KOI8-R fonts, but this ones scaled better.</para>
there. This port install latest version of KOI8-R fonts. XFree86
3.3 already have some KOI8-R fonts, but this ones scaled
better.</para>
<para>Check find <literal>"Files"</literal> section
in your <filename>/etc/XF86Config</filename>, following
lines must be before any other <literal>FontPath</literal>
entries:</para>
<para>Check find <literal>"Files"</literal> section in your
<filename>/etc/XF86Config</filename>, following lines must be
before any other <literal>FontPath</literal> entries:</para>
<programlisting>
FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/misc"
FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/75dpi"
FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/100dpi"</programlisting>
<para>If you use high resolution video mode, swap 75 dpi and
100 dpi lines.</para>
<para>If you use high resolution video mode, swap 75 dpi and 100 dpi
lines.</para>
</step>
<step>
<para>To activate Russian keyboard add
<programlisting>
XkbKeymap "xfree86(ru)"</programlisting> line into
<literal>"Keyboard"</literal> section in your
<filename>/etc/XF86Config</filename>, also make sure that
<literal>XkbDisable</literal> is turned off
(commented out) there.</para>
XkbKeymap "xfree86(ru)"</programlisting>
<para>RUS/LAT switch will be <literal>CapsLock</literal>. Old CapsLock function still
available via <literal>Shift+CapsLock</literal>
(in LAT mode only).</para>
line into <literal>"Keyboard"</literal> section in your
<filename>/etc/XF86Config</filename>, also make sure that
<literal>XkbDisable</literal> is turned off (commented out)
there.</para>
<para>RUS/LAT switch will be <literal>CapsLock</literal>. Old
CapsLock function still available via
<literal>Shift+CapsLock</literal> (in LAT mode only).</para>
<note>
<para>Russian XKB keyboard may not work with old XFree86
versions, see <link
linkend="russian-note">locale note</link> for more info.
Russian XKB keyboard may not work with non-localized
applications too, minimally localized application should
call <literal>XtSetLanguageProc
(NULL, NULL, NULL);</literal> function early in the program.</para>
<para>Russian XKB keyboard may not work with old XFree86 versions,
see <link linkend="russian-note">locale note</link> for more
info. Russian XKB keyboard may not work with non-localized
applications too, minimally localized application should call
<literal>XtSetLanguageProc (NULL, NULL, NULL);</literal>
function early in the program.</para>
</note>
</step>
</procedure>
</sect2>
</sect1>
<sect1 id="german">
<title>German Language (ISO 8859-1)</title>
<para>Slaven Rezic <email>eserte@cs.tu-berlin.de</email> wrote a tutorial how to use umlauts on a FreeBSD machine. The tutorial is written in German and available at <ulink URL="http://www.de.freebsd.org/de/umlaute/">http://www.de.freebsd.org/de/umlaute/</ulink>.</para>
<para>Slaven Rezic <email>eserte@cs.tu-berlin.de</email> wrote a tutorial
how to use umlauts on a FreeBSD machine. The tutorial is written in
German and available at <ulink
URL="http://www.de.freebsd.org/de/umlaute/">http://www.de.freebsd.org/de/umlaute/</ulink>.</para>
</sect1>
</chapter>
</chapter>
<!--
Local Variables:

760
en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml
View file

File diff suppressed because it is too large Load diff

466
en_US.ISO8859-1/books/handbook/mail/chapter.sgml
View file

@ -1,37 +1,34 @@
<chapter id="mail">
<chapter id="mail">
<title>Electronic Mail</title>
<para><emphasis>Contributed by &a.wlloyd;.</emphasis></para>
<para>Electronic Mail configuration is the subject of many <link
linkend="bibliography">System Administration</link> books. If you
plan on doing anything beyond setting up one mailhost for your
network, you need industrial strength help.</para>
<para>Some parts of E-Mail configuration are controlled in the Domain
Name System (DNS). If you are going to run your own own DNS server
check out <filename>/etc/namedb</filename> and <command>man -k named</command> for more information.</para>
linkend="bibliography">System Administration</link> books. If you plan
on doing anything beyond setting up one mailhost for your network, you
need industrial strength help.</para>
<para>Some parts of E-Mail configuration are controlled in the Domain Name
System (DNS). If you are going to run your own own DNS server check out
<filename>/etc/namedb</filename> and <command>man -k named</command> for
more information.</para>
<sect1>
<title>Basic Information</title>
<para>These are the major programs involved in an E-Mail exchange. A
&ldquo;mailhost&rdquo; is a server that is
responsible for delivering and receiving all email for your host,
and possibly your network.</para>
&ldquo;mailhost&rdquo; is a server that is responsible for delivering
and receiving all email for your host, and possibly your network.</para>
<sect2>
<title>User program</title>
<para>This is a program like <application >elm</application>, <application>pine</application>,
<application>mail</application>, or something more sophisticated like a WWW
browser. This program will simply pass off all e-mail
transactions to the local &ldquo;mailhost&rdquo; ,
either by calling <command>sendmail</command> or
delivering it over TCP.</para>
<para>This is a program like <application >elm</application>,
<application>pine</application>, <application>mail</application>, or
something more sophisticated like a WWW browser. This program will
simply pass off all e-mail transactions to the local
&ldquo;mailhost&rdquo; , either by calling <command>sendmail</command>
or delivering it over TCP.</para>
</sect2>
<sect2>
@ -39,150 +36,137 @@
<para>Usually this program is <command>sendmail</command> or
<command>smail</command> running in the background. Turn it off or
change the command line options in
<filename>/etc/rc.conf</filename> (or, prior to FreeBSD 2.2.2,
<filename>/etc/sysconfig</filename>). It is best to leave it on,
unless you have a specific reason to want it off. Example: You
are building a <link
change the command line options in <filename>/etc/rc.conf</filename>
(or, prior to FreeBSD 2.2.2, <filename>/etc/sysconfig</filename>). It
is best to leave it on, unless you have a specific reason to want it
off. Example: You are building a <link
linkend="firewalls">Firewall</link>.</para>
<para>You should be aware that <command>sendmail</command> is a potential weak link in a
secure site. Some versions of <command>sendmail</command> have known security
problems.</para>
<para>You should be aware that <command>sendmail</command> is a
potential weak link in a secure site. Some versions of
<command>sendmail</command> have known security problems.</para>
<para><command>sendmail</command> does two jobs. It looks after delivering
and receiving mail.</para>
<para><command>sendmail</command> does two jobs. It looks after
delivering and receiving mail.</para>
<para>If <command>sendmail</command>
needs to deliver mail off your site it will look up in
the DNS to determine the actual host that will receive mail for
the destination.</para>
<para>If it is acting as a delivery agent <command>sendmail</command> will take the message from the
local queue and deliver it across the Internet to another sendmail
on the receivers computer.</para>
<para>If <command>sendmail</command> needs to deliver mail off your site
it will look up in the DNS to determine the actual host that will
receive mail for the destination.</para>
<para>If it is acting as a delivery agent <command>sendmail</command>
will take the message from the local queue and deliver it across the
Internet to another sendmail on the receivers computer.</para>
</sect2>
<sect2>
<title>DNS &mdash; Name Service</title>
<para>The Domain Name System and its daemon <command>named</command>, contain the database mapping
hostname to IP address, and hostname to mailhost. The IP address
is specified in an A record. The MX record specifies the
mailhost that will receive mail for you. If you do not have a
MX record mail for your hostname, the mail will be delivered to
<para>The Domain Name System and its daemon <command>named</command>,
contain the database mapping hostname to IP address, and hostname to
mailhost. The IP address is specified in an A record. The MX record
specifies the mailhost that will receive mail for you. If you do not
have a MX record mail for your hostname, the mail will be delivered to
your host directly.</para>
<para>Unless you are running your own DNS server, you will not be
able to change any information in the DNS yourself. If you are
using an Internet Provider, speak to them.</para>
<para>Unless you are running your own DNS server, you will not be able
to change any information in the DNS yourself. If you are using an
Internet Provider, speak to them.</para>
</sect2>
<sect2>
<title>POP Servers</title>
<para>This program gets the mail from your mailbox and gives it to
your browser. If you want to run a POP server on your computer,
you will need to do 2 things.</para>
<para>This program gets the mail from your mailbox and gives it to your
browser. If you want to run a POP server on your computer, you will
need to do 2 things.</para>
<procedure>
<step>
<para>Get pop software from the <ulink
URL="../ports/mail.html">Ports collection</ulink> that
can be found in <filename>/usr/ports</filename> or packages
collection. This handbook section has a complete reference
on the <link linkend="ports">Ports</link> system.</para>
URL="../ports/mail.html">Ports collection</ulink> that can be
found in <filename>/usr/ports</filename> or packages collection.
This handbook section has a complete reference on the <link
linkend="ports">Ports</link> system.</para>
</step>
<step>
<para>Modify <filename>/etc/inetd.conf</filename>
to load the POP server.</para>
<para>Modify <filename>/etc/inetd.conf</filename> to load the POP
server.</para>
</step>
</procedure>
<para>The pop program will have instructions with it. Read
them.</para>
<para>The pop program will have instructions with it. Read them.</para>
</sect2>
</sect1>
<sect1>
<title>Configuration</title>
<sect2>
<title>Basic</title>
<para>As your FreeBSD system comes &ldquo;out of the box&rdquo;[TM], you should
be able to send E-mail to external hosts as long as you have
<para>As your FreeBSD system comes &ldquo;out of the box&rdquo;[TM], you
should be able to send E-mail to external hosts as long as you have
<filename>/etc/resolv.conf</filename> setup or are running a name
server. If you want to have mail for your host delivered to your
specific host,there are two methods:</para>
<itemizedlist>
<listitem>
<para>Run a name server (<command>man -k named</command>) and have your own domain
<hostid role="domainname">smallminingco.com </hostid></para>
<para>Run a name server (<command>man -k named</command>) and have
your own domain <hostid role="domainname">smallminingco.com
</hostid></para>
</listitem>
<listitem>
<para>Get mail delivered to the current DNS name for your host.
Ie: <hostid role="fqdn">dorm6.ahouse.school.edu </hostid></para>
<para>Get mail delivered to the current DNS name for your host. Ie:
<hostid role="fqdn">dorm6.ahouse.school.edu </hostid></para>
</listitem>
</itemizedlist>
<para>No matter what option you choose, to have mail delivered
directly to your host, you must be a full Internet host. You must
have a permanent IP address. IE: NO dynamic PPP. If you are
behind a firewall, the firewall must be passing on smtp traffic to
you. From <filename>/etc/services</filename>:</para>
<para>No matter what option you choose, to have mail delivered directly
to your host, you must be a full Internet host. You must have a
permanent IP address. IE: NO dynamic PPP. If you are behind a
firewall, the firewall must be passing on smtp traffic to you. From
<filename>/etc/services</filename>:</para>
<programlisting
>smtp 25/tcp mail #Simple Mail Transfer</programlisting>
<programlisting>
smtp 25/tcp mail #Simple Mail Transfer</programlisting>
<para>If you
want to receive mail at your host itself, you must make sure that
the DNS MX entry points to your host address, or there is no MX
entry for your DNS name.</para>
<para>If you want to receive mail at your host itself, you must make
sure that the DNS MX entry points to your host address, or there is no
MX entry for your DNS name.</para>
<para>Try this:</para>
<screen>&prompt.root; <userinput>hostname</userinput>
newbsdbox.freebsd.org
&prompt.root; <userinput>host newbsdbox.freebsd.org</userinput>
newbsdbox.freebsd.org has address 204.216.27.xx</screen>
<para>If that is all that comes out for your machine, mail directory
to <email>root@newbsdbox.freebsd.org</email>
will work no problems.</para>
<para>If that is all that comes out for your machine, mail directory to
<email>root@newbsdbox.freebsd.org</email> will work no
problems.</para>
<para>If instead, you have this:</para>
<screen>&prompt.root; <userinput>host newbsdbox.freebsd.org</userinput>
newbsdbox.FreeBSD.org has address 204.216.27.xx
newbsdbox.FreeBSD.org mail is handled (pri=10) by freefall.FreeBSD.org</screen>
<para>All mail sent to your host directly will end up on
<hostid>freefall</hostid>, under the same username.</para>
<para>All mail sent to your host
directly will end up on <hostid>freefall</hostid>, under the same username.</para>
<para>This information is setup in your domain name server. This should
be the same host that is listed as your primary nameserver in
<filename>/etc/resolv.conf</filename></para>
<para>This information is setup in your domain name server. This
should be the same host that is listed as your primary nameserver
in <filename>/etc/resolv.conf</filename></para>
<para>The DNS record that carries mail routing information is the Mail
eXchange entry. If no MX entry exists, mail will be delivered directly
to the host by way of the Address record.</para>
<para>The DNS record that carries mail routing information is the
Mail eXchange entry. If no MX entry exists, mail will be
delivered directly to the host by way of the Address
record.</para>
<para>The MX entry for <hostid role="fqdn">freefall.freebsd.org</hostid> at one time.</para>
<para>The MX entry for <hostid role="fqdn">freefall.freebsd.org</hostid>
at one time.</para>
<programlisting>
freefall MX 30 mail.crl.net
@ -193,39 +177,38 @@ freefall MX 20 who.cdrom.com
freefall A 204.216.27.xx
freefall CNAME www.FreeBSD.org</programlisting>
<para><hostid>freefall</hostid> has many MX entries. The lowest MX number gets the
mail in the end. The others will queue mail temporarily, if
<hostid>freefall</hostid> is busy or down.</para>
<para><hostid>freefall</hostid> has many MX entries. The lowest MX
number gets the mail in the end. The others will queue mail
temporarily, if <hostid>freefall</hostid> is busy or down.</para>
<para>Alternate MX sites should have separate connections to the
Internet, to be most useful. An Internet Provider or other
friendly site can provide this service.</para>
<para><command>dig</command>, <command>nslookup</command>,
and <command>host</command> are your friends.</para>
Internet, to be most useful. An Internet Provider or other friendly
site can provide this service.</para>
<para><command>dig</command>, <command>nslookup</command>, and
<command>host</command> are your friends.</para>
</sect2>
<sect2 id="mail-domain">
<title>Mail for your Domain (Network).</title>
<para>To setup up a network mailhost, you need to direct the mail
from arriving at all the workstations. In other words, you want to
hijack all mail for <hostid role="domainname">*.smallminingco.com
</hostid> and divert it to one machine, your &ldquo;mailhost&rdquo;.</para>
<para>To setup up a network mailhost, you need to direct the mail from
arriving at all the workstations. In other words, you want to hijack
all mail for <hostid role="domainname">*.smallminingco.com </hostid>
and divert it to one machine, your &ldquo;mailhost&rdquo;.</para>
<para>The network users on their workstations will most likely pick
up their mail over POP or telnet.</para>
<para>The network users on their workstations will most likely pick up
their mail over POP or telnet.</para>
<para>A user account with the <emphasis>same username</emphasis> should exist on both
machines. Please use <command>adduser</command> to do
<para>A user account with the <emphasis>same username</emphasis> should
exist on both machines. Please use <command>adduser</command> to do
this as required. If you set the <literal>shell</literal> to
<literal>/nonexistent</literal>
the user will not be allowed to login.</para>
<literal>/nonexistent</literal> the user will not be allowed to
login.</para>
<para>The mailhost that you will be using must be designated the
Mail eXchange for each workstation. This must be arranged in DNS
(ie BIND, named). Please refer to a Networking book for in-depth
Mail eXchange for each workstation. This must be arranged in DNS (ie
BIND, named). Please refer to a Networking book for in-depth
information.</para>
<para>You basically need to add these lines in your DNS server.</para>
@ -234,44 +217,45 @@ freefall CNAME www.FreeBSD.org</programlisting>
pc24.smallminingco.com A <replaceable>xxx.xxx.xxx.xxx</replaceable> ; Workstation ip
MX 10 smtp.smallminingco.com ; Your mailhost</programlisting>
<para>You cannot do this yourself unless you are running a DNS
server. If you do not want to run a DNS server, get somebody else
like your Internet Provider to do it.</para>
<para>You cannot do this yourself unless you are running a DNS server.
If you do not want to run a DNS server, get somebody else like your
Internet Provider to do it.</para>
<para>This will redirect mail for the workstation to the Mail
eXchange host. It does not matter what machine the A record
points to, the mail will be sent to the MX host.</para>
<para>This will redirect mail for the workstation to the Mail eXchange
host. It does not matter what machine the A record points to, the mail
will be sent to the MX host.</para>
<para>This feature is used to implement Virtual E-Mail Hosting.</para>
<para>Example</para>
<para>I have a customer with domain foo.bar and I want all mail for
foo.bar to be sent to my machine smtp.smalliap.com. You must make
an entry in your DNS server like:</para>
foo.bar to be sent to my machine smtp.smalliap.com. You must make an
entry in your DNS server like:</para>
<programlisting>
foo.bar MX 10 smtp.smalliap.com ; your mailhost</programlisting>
<para>The A record is not needed if you only
want E-Mail for the domain. IE: Don't expect <command>ping foo.bar</command>
to work unless an Address record for <filename>foo.bar</filename>
exists as well.</para>
<para>The A record is not needed if you only want E-Mail for the domain.
IE: Don't expect <command>ping foo.bar</command> to work unless an
Address record for <filename>foo.bar</filename> exists as well.</para>
<para>On the mailhost that actually accepts mail for final delivery
to a mailbox, <command>sendmail</command> must be told what hosts it will be
accepting mail for.</para>
<para>On the mailhost that actually accepts mail for final delivery to a
mailbox, <command>sendmail</command> must be told what hosts it will
be accepting mail for.</para>
<para>Add <literal>pc24.smallminingco.com</literal> to <filename>/etc/sendmail.cw</filename> (if you are
using <literal>FEATURE(use_cw_file)</literal>), or add a <literal>Cw myhost.smalliap.com</literal>
line to <filename>/etc/sendmail.cf</filename></para>
<para>If you plan on doing anything serious with <command>sendmail</command> you should install the <command>sendmail</command>
source. The source has plenty of documentation with it. You will
find information on getting <command>sendmail</command>
source from <link linkend="sendmailuucp">the UUCP
information</link>.</para>
<para>Add <literal>pc24.smallminingco.com</literal> to
<filename>/etc/sendmail.cw</filename> (if you are using
<literal>FEATURE(use_cw_file)</literal>), or add a <literal>Cw
myhost.smalliap.com</literal> line to
<filename>/etc/sendmail.cf</filename></para>
<para>If you plan on doing anything serious with
<command>sendmail</command> you should install the
<command>sendmail</command> source. The source has plenty of
documentation with it. You will find information on getting
<command>sendmail</command> source from <link
linkend="sendmailuucp">the UUCP information</link>.</para>
</sect2>
<sect2 id="sendmailuucp">
@ -279,65 +263,56 @@ foo.bar MX 10 smtp.smalliap.com ; your mailhost</programlistin
<para><emphasis>Stolen from the FAQ.</emphasis></para>
<para>The sendmail configuration that ships with FreeBSD is suited
for sites that connect directly to the Internet. Sites that wish
to exchange their mail via UUCP must install another <command>sendmail</command>
configuration file.</para>
<para>The sendmail configuration that ships with FreeBSD is suited for
sites that connect directly to the Internet. Sites that wish to
exchange their mail via UUCP must install another
<command>sendmail</command> configuration file.</para>
<para>Tweaking <filename>/etc/sendmail.cf</filename> manually is
considered something for purists. Sendmail version 8 comes with a
new approach of generating config files via some <command>m4</command> preprocessing, where the actual
hand-crafted configuration is on a higher abstraction level. You
should use the configuration files under
considered something for purists. Sendmail version 8 comes with a new
approach of generating config files via some <command>m4</command>
preprocessing, where the actual hand-crafted configuration is on a
higher abstraction level. You should use the configuration files under
<filename>/usr/src/usr.sbin/sendmail/cf</filename>.</para>
<para>If you did not install your system with full sources, the
<command>sendmail</command> config stuff has been broken out into a separate source
distribution tarball just for you. Assuming you have your CD-ROM
mounted, do:</para>
<command>sendmail</command> config stuff has been broken out into a
separate source distribution tarball just for you. Assuming you have
your CD-ROM mounted, do:</para>
<screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>tar -xvzf /cdrom/dists/src/ssmailcf.aa</userinput></screen>
<para>Do not panic, this is only a few hundred kilobytes in size.
The file <filename>README</filename> in the <filename>cf</filename> directory can serve as a basic
introduction to m4 configuration.</para>
<para>Do not panic, this is only a few hundred kilobytes in size. The
file <filename>README</filename> in the <filename>cf</filename>
directory can serve as a basic introduction to m4
configuration.</para>
<para>For UUCP delivery, you are best advised to use the
<emphasis>mailertable</emphasis> feature. This constitutes a
database that <command>sendmail</command> can use to base its routing decision
<emphasis>mailertable</emphasis> feature. This constitutes a database
that <command>sendmail</command> can use to base its routing decision
upon.</para>
<para>First, you have to create your <filename>.mc</filename> file.
The directory
<filename>/usr/src/usr.sbin/sendmail/cf/cf</filename> is the home
of these files. Look around, there are already a few examples.
Assuming you have named your file <filename>foo.mc</filename>, all
you need to do in order to convert it into a valid
<para>First, you have to create your <filename>.mc</filename> file. The
directory <filename>/usr/src/usr.sbin/sendmail/cf/cf</filename> is the
home of these files. Look around, there are already a few examples.
Assuming you have named your file <filename>foo.mc</filename>, all you
need to do in order to convert it into a valid
<filename>sendmail.cf</filename> is:</para>
<screen>&prompt.root; <userinput>cd /usr/src/usr.sbin/sendmail/cf/cf</userinput>
&prompt.root; <userinput>make foo.cf</userinput></screen>
<para>If you don't have a <filename>/usr/obj</filename> hiearchy,
then:</para>
<screen>&prompt.root; <userinput>cp foo.cf /etc/sendmail.cf</userinput></screen>
<para>Otherwise:</para>
<screen>&prompt.root; <userinput>cp /usr/obj/`pwd`/foo.cf /etc/sendmail.cf</userinput></screen>
<para>A typical <filename>.mc</filename> file might look
like:</para>
<para>A typical <filename>.mc</filename> file might look like:</para>
<programlisting>
include(`../m4/cf.m4')
@ -358,13 +333,12 @@ MAILER(uucp)
Cw <replaceable>your.alias.host.name</replaceable>
Cw <replaceable>youruucpnodename.UUCP</replaceable></programlisting>
<para>The <literal>nodns</literal> and
<literal>nocanonify</literal> features will prevent any usage of
the DNS during mail delivery. The <literal>UUCP_RELAY</literal>
clause is needed for bizarre reasons, do not ask. Simply put an
Internet hostname there that is able to handle .UUCP pseudo-domain
addresses; most likely, you will enter the mail relay of your ISP
there.</para>
<para>The <literal>nodns</literal> and <literal>nocanonify</literal>
features will prevent any usage of the DNS during mail delivery. The
<literal>UUCP_RELAY</literal> clause is needed for bizarre reasons, do
not ask. Simply put an Internet hostname there that is able to handle
.UUCP pseudo-domain addresses; most likely, you will enter the mail
relay of your ISP there.</para>
<para>Once you have this, you need this file called
<filename>/etc/mailertable</filename>. A typical example of this
@ -381,36 +355,35 @@ interface-business.de uucp-dom:if-bus
uucp-dom:horus if-bus.UUCP
uucp-dom:if-bus . uucp-dom:sax</programlisting>
<para>As you can see, this is part of a real-life file. The first
three lines handle special cases where domain-addressed mail
should not be sent out to the default route, but instead to some
UUCP neighbor in order to &ldquo;shortcut&rdquo; the delivery path. The
next line handles mail to the local Ethernet domain that can be
delivered using SMTP. Finally, the UUCP neighbors are mentioned
in the .UUCP pseudo-domain notation, to allow for a
<literal>uucp-neighbor!recipient</literal> override of the default rules. The
last line is always a single dot, matching everything else, with
UUCP delivery to a UUCP neighbor that serves as your universal
<para>As you can see, this is part of a real-life file. The first three
lines handle special cases where domain-addressed mail should not be
sent out to the default route, but instead to some UUCP neighbor in
order to &ldquo;shortcut&rdquo; the delivery path. The next line
handles mail to the local Ethernet domain that can be delivered using
SMTP. Finally, the UUCP neighbors are mentioned in the .UUCP
pseudo-domain notation, to allow for a
<literal>uucp-neighbor!recipient</literal> override of the default
rules. The last line is always a single dot, matching everything else,
with UUCP delivery to a UUCP neighbor that serves as your universal
mail gateway to the world. All of the node names behind the
<literal>uucp-dom:</literal> keyword must be valid UUCP
neighbors, as you can verify using the command <command>uuname</command>.</para>
<literal>uucp-dom:</literal> keyword must be valid UUCP neighbors, as
you can verify using the command <command>uuname</command>.</para>
<para>As a reminder that this file needs to be converted into a DBM
database file before being usable, the command line to accomplish
this is best placed as a comment at the top of the <filename>mailertable</filename>.
You always have to execute this command each time you change your
database file before being usable, the command line to accomplish this
is best placed as a comment at the top of the
<filename>mailertable</filename>. You always have to execute this
command each time you change your
<filename>mailertable</filename>.</para>
<para>Final hint: if you are uncertain whether some particular mail
routing would work, remember the <option>-bt</option> option to
<command>sendmail</command>. It starts <command>sendmail</command>
in &ldquo;address test
mode&rdquo;; simply enter <literal>0</literal>, followed by the address
you wish to test for the mail routing. The last line tells you
the used internal mail agent, the destination host this agent will
be called with, and the (possibly translated) address. Leave this
mode by typing Control-D.</para>
<command>sendmail</command>. It starts <command>sendmail</command> in
&ldquo;address test mode&rdquo;; simply enter <literal>0</literal>,
followed by the address you wish to test for the mail routing. The
last line tells you the used internal mail agent, the destination host
this agent will be called with, and the (possibly translated) address.
Leave this mode by typing Control-D.</para>
<screen>&prompt.user; <userinput>sendmail -bt</userinput>
ADDRESS TEST MODE (ruleset 3 NOT automatically invoked)
@ -419,8 +392,6 @@ Enter &lt;ruleset&gt; &lt;address&gt;
rewrite: ruleset 0 input: foo @ interface-business . de
&hellip;
rewrite: ruleset 0 returns: $# uucp-dom $@ if-bus $: foo &lt; @ interface-business . de</screen>
</sect2>
</sect1>
@ -429,30 +400,31 @@ rewrite: ruleset 0 returns: $# uucp-dom $@ if-bus $: foo &lt; @ interface-busin
<para><emphasis>Migration from FAQ.</emphasis></para>
<sect2>
<title>Why do I have to use the FQDN for hosts on my site?</title>
<para>You will probably find that the host is actually in a
different domain; for example, if you are in <hostid role="fqdn">foo.bar.edu</hostid> and you
wish to reach a host called <hostid>mumble</hostid> in the <hostid
role="domainname">bar.edu</hostid> domain, you
will have to refer to it by the fully-qualified domain name,
<hostid role="fqdn">mumble.bar.edu</hostid>, instead of just <hostid>mumble</hostid>.</para>
<para>You will probably find that the host is actually in a different
domain; for example, if you are in <hostid
role="fqdn">foo.bar.edu</hostid> and you wish to reach a host called
<hostid>mumble</hostid> in the <hostid
role="domainname">bar.edu</hostid> domain, you will have to refer to
it by the fully-qualified domain name, <hostid
role="fqdn">mumble.bar.edu</hostid>, instead of just
<hostid>mumble</hostid>.</para>
<para>Traditionally, this was allowed by BSD BIND resolvers. However
the current version of <application>BIND</application> that ships with
<para>Traditionally, this was allowed by BSD BIND resolvers. However the
current version of <application>BIND</application> that ships with
FreeBSD no longer provides default abbreviations for non-fully
qualified domain names other than the domain you are in. So an
unqualified host <hostid>mumble</hostid> must either
be found as <hostid role="fqdn">mumble.foo.bar.edu</hostid>, or
it will be searched for in the root domain.</para>
unqualified host <hostid>mumble</hostid> must either be found as
<hostid role="fqdn">mumble.foo.bar.edu</hostid>, or it will be
searched for in the root domain.</para>
<para>This is different from the previous behavior, where the search
continued across <hostid role="domainname">mumble.bar.edu</hostid>,
and <hostid role="domainname">mumble.edu</hostid>. Have a look at
RFC 1535 for why this was considered bad practice, or even a
security hole.</para>
and <hostid role="domainname">mumble.edu</hostid>. Have a look at RFC
1535 for why this was considered bad practice, or even a security
hole.</para>
<para>As a good workaround, you can place the line
@ -464,15 +436,14 @@ search foo.bar.edu bar.edu</programlisting>
<programlisting>
domain foo.bar.edu</programlisting>
into your <filename>/etc/resolv.conf</filename>. However,
make sure that the search order does not go beyond the &ldquo;boundary
between local and public administration&rdquo;, as RFC 1535 calls
it.</para>
into your <filename>/etc/resolv.conf</filename>. However, make sure
that the search order does not go beyond the &ldquo;boundary between
local and public administration&rdquo;, as RFC 1535 calls it.</para>
</sect2>
<sect2>
<title>Sendmail says <errorname>mail loops back to myself</errorname></title>
<title>Sendmail says <errorname>mail loops back to
myself</errorname></title>
<para>This is answered in the sendmail FAQ as follows:</para>
@ -495,41 +466,41 @@ to /etc/sendmail.cf.</programlisting>
<filename>/usr/src/usr.sbin/sendmail</filename> and is recommended
reading if you want to do any &ldquo;tweaking&rdquo; of your mail
setup.</para>
</sect2>
<sect2>
<title>How can I do E-Mail with a dialup PPP host?</title>
<para>You want to connect a FreeBSD box on a lan, to the Internet.
The FreeBSD box will be a mail gateway for the lan. The PPP
connection is non-dedicated.</para>
<para>You want to connect a FreeBSD box on a lan, to the Internet. The
FreeBSD box will be a mail gateway for the lan. The PPP connection is
non-dedicated.</para>
<para>There are at least two way to do this.</para>
<para>The other is to use UUCP.</para>
<para>The key is to get a Internet site to provide secondary MX
services for your domain. For example:</para>
<para>The key is to get a Internet site to provide secondary MX services
for your domain. For example:</para>
<programlisting>
bigco.com. MX 10 bigco.com.
MX 20 smalliap.com.</programlisting>
<para>Only one host should be specified as the final recipient ( add
<literal>Cw bigco.com</literal> in <filename>/etc/sendmail.cf</filename> on
bigco.com).</para>
<literal>Cw bigco.com</literal> in
<filename>/etc/sendmail.cf</filename> on bigco.com).</para>
<para>When the senders <command>sendmail</command> is trying to deliver the mail it
will try to connect to you over the modem link. It will most
likely time out because you are not online. <command>sendmail</command> will
automatically deliver it to the secondary MX site, ie your
Internet provider. The secondary MX site will try every
(<literal>sendmail_flags = "-bd -q15m"</literal> in
<filename>/etc/rc.conf</filename> ) 15 minutes to connect to your
host to deliver the mail to the primary MX site.</para>
<para>When the senders <command>sendmail</command> is trying to deliver
the mail it will try to connect to you over the modem link. It will
most likely time out because you are not online.
<command>sendmail</command> will automatically deliver it to the
secondary MX site, ie your Internet provider. The secondary MX site
will try every (<literal>sendmail_flags = "-bd -q15m"</literal> in
<filename>/etc/rc.conf</filename> ) 15 minutes to connect to your host
to deliver the mail to the primary MX site.</para>
<para>You might want to use something like this as a login script.</para>
<para>You might want to use something like this as a login
script.</para>
<programlisting>
#!/bin/sh
@ -537,11 +508,10 @@ bigco.com. MX 10 bigco.com.
( sleep 60 ; /usr/sbin/sendmail -q ) &amp;
/usr/sbin/ppp -direct pppbigco</programlisting>
<para>If you are going to create a separate
login script for a user you could use <command>sendmail
-qRbigco.com</command> instead in the script above. This will
force all mail in your queue for bigco.com to be processed
immediately.</para>
<para>If you are going to create a separate login script for a user you
could use <command>sendmail -qRbigco.com</command> instead in the
script above. This will force all mail in your queue for bigco.com to
be processed immediately.</para>
<para>A further refinement of the situation is as follows.</para>
@ -574,11 +544,9 @@ the customer connection. You then send to your customer. Only works for
"hosts", so you need to get your customer to name their mail machine
"customer.com" as well as "hostname.customer.com" in the DNS. Just put
an A record in the DNS for "customer.com".</programlisting>
</sect2>
</sect1>
</chapter>
</chapter>
<!--
Local Variables:

636
en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml
View file

File diff suppressed because it is too large Load diff

18
en_US.ISO8859-1/books/handbook/pgpkeys/chapter.sgml
View file

@ -1,17 +1,16 @@
<chapter id="pgpkeys">
<chapter id="pgpkeys">
<title>PGP keys</title>
<para>In case you need to verify a signature or send encrypted email to
one of the officers or core team members a number of keys are
provided here for your convenience.</para>
<para>In case you need to verify a signature or send encrypted email to one
of the officers or core team members a number of keys are provided here
for your convenience.</para>
<sect1>
<title>Officers</title>
<sect2>
<title>FreeBSD Security Officer <email>security-officer@freebsd.org</email></title>
<title>FreeBSD Security Officer
<email>security-officer@freebsd.org</email></title>
<programlisting>
FreeBSD Security Officer &lt;security-officer@freebsd.org&gt;
@ -43,7 +42,6 @@ v4Xhp6a8RtDdUMBOTtro16iulGiRrCKxzVgEl4i+9Z0ZiE6BWlg5AetoF5n3mGk1
lw==
=ipyA
-----END PGP PUBLIC KEY BLOCK-----</programlisting>
</sect2>
<sect2>
@ -74,14 +72,12 @@ RzUrblyF84tJyA7Rr1p+A7dxf7je3Zx5QMEXosWL1WGnS5vC9YH2WZwv6sCU61gU
rSy9z8KHlBEHh+Z6fdRMrjd9byPf+n3cktT0NhS23oXB1ZhNZcB2KKhVPlNctMqO
3gTYx+Nlo6xqjR+J2NnBYU8p =7fQV
-----END PGP PUBLIC KEY BLOCK-----</programlisting>
</sect2>
</sect1>
<sect1>
<title>Core Team members</title>
<sect2>
<title>&a.asami;</title>
@ -564,7 +560,7 @@ xDZaEUQEbWqxfiwuzizAjkaxrW7dBbWILwWqrYF5TXClw+oUU/oIUW4t6t+GpAO1
-----END PGP PUBLIC KEY BLOCK-----</programlisting>
</sect2>
</sect1>
</chapter>
</chapter>
<!--
Local Variables:

271
en_US.ISO8859-1/books/handbook/policies/chapter.sgml
View file

@ -1,11 +1,10 @@
<chapter id="policies">
<chapter id="policies">
<title>Source Tree Guidelines and Policies</title>
<para><emphasis>Contributed by &a.phk;.</emphasis></para>
<para>This chapter documents various guidelines and policies in force
for the FreeBSD source tree.</para>
<para>This chapter documents various guidelines and policies in force for
the FreeBSD source tree.</para>
<sect1 id="policies-maintainer">
<title><makevar>MAINTAINER</makevar> on Makefiles</title>
@ -13,36 +12,33 @@
<para>June 1996.</para>
<para>If a particular portion of the FreeBSD distribution is being
maintained by a person or group of persons, they can communicate
this fact to the world by adding a
maintained by a person or group of persons, they can communicate this
fact to the world by adding a
<programlisting>
MAINTAINER= email-addresses</programlisting>
line to the <filename>Makefile</filename>s covering this portion
of the source tree.</para>
line to the <filename>Makefile</filename>s covering this portion of the
source tree.</para>
<para>The semantics of this are as follows:</para>
<para>The maintainer owns and is responsible for that code. This
means that he is responsible for fixing bugs and answer problem
reports pertaining to that piece of the code, and in the case of
contributed software, for tracking new versions, as
appropriate.</para>
<para>The maintainer owns and is responsible for that code. This means
that he is responsible for fixing bugs and answer problem reports
pertaining to that piece of the code, and in the case of contributed
software, for tracking new versions, as appropriate.</para>
<para>Changes to directories which have a maintainer defined shall be
sent to the maintainer for review before being committed. Only if
the maintainer does not respond for an unacceptable period of time,
to several emails, will it be acceptable to commit changes without
review by the maintainer. However, it is suggested that you try and
have the changes reviewed by someone else if at all
possible.</para>
<para>Changes to directories which have a maintainer defined shall be sent
to the maintainer for review before being committed. Only if the
maintainer does not respond for an unacceptable period of time, to
several emails, will it be acceptable to commit changes without review
by the maintainer. However, it is suggested that you try and have the
changes reviewed by someone else if at all possible.</para>
<para>It is of course not acceptable to add a person or group as
maintainer unless they agree to assume this duty. On the other hand
it doesn't have to be a committer and it can easily be a group of
maintainer unless they agree to assume this duty. On the other hand it
doesn't have to be a committer and it can easily be a group of
people.</para>
</sect1>
<sect1>
@ -52,31 +48,31 @@ MAINTAINER= email-addresses</programlisting>
<para>June 1996.</para>
<para>Some parts of the FreeBSD distribution consist of software that
is actively being maintained outside the FreeBSD project. For
historical reasons, we call this <emphasis>contributed</emphasis>
software. Some examples are perl, gcc and patch.</para>
<para>Some parts of the FreeBSD distribution consist of software that is
actively being maintained outside the FreeBSD project. For historical
reasons, we call this <emphasis>contributed</emphasis> software. Some
examples are perl, gcc and patch.</para>
<para>Over the last couple of years, various methods have been used in
dealing with this type of software and all have some number of
advantages and drawbacks. No clear winner has emerged.</para>
<para>Since this is the case, after some debate one of these methods
has been selected as the &ldquo;official&rdquo; method and will be required for
future imports of software of this kind. Furthermore, it is
strongly suggested that existing contributed software converge on
this model over time, as it has significant advantages over the old
method, including the ability to easily obtain diffs relative to the
&ldquo;official&rdquo; versions of the source by everyone (even without cvs
access). This will make it significantly easier to return changes
<para>Since this is the case, after some debate one of these methods has
been selected as the &ldquo;official&rdquo; method and will be required
for future imports of software of this kind. Furthermore, it is
strongly suggested that existing contributed software converge on this
model over time, as it has significant advantages over the old method,
including the ability to easily obtain diffs relative to the
&ldquo;official&rdquo; versions of the source by everyone (even without
cvs access). This will make it significantly easier to return changes
to the primary developers of the contributed software.</para>
<para>Ultimately, however, it comes down to the people actually doing
the work. If using this model is particularly unsuited to the
package being dealt with, exceptions to these rules may be granted
only with the approval of the core team and with the general
consensus of the other developers. The ability to maintain the
package in the future will be a key issue in the decisions.</para>
<para>Ultimately, however, it comes down to the people actually doing the
work. If using this model is particularly unsuited to the package being
dealt with, exceptions to these rules may be granted only with the
approval of the core team and with the general consensus of the other
developers. The ability to maintain the package in the future will be a
key issue in the decisions.</para>
<note>
<para>Because of some unfortunate design limitations with the RCS file
@ -93,76 +89,72 @@ MAINTAINER= email-addresses</programlisting>
language will be used as example of how this model works:</para>
<para><filename>src/contrib/tcl</filename> contains the source as
distributed by the maintainers of this package. Parts that are
entirely not applicable for FreeBSD can be removed. In the case of
Tcl, the <filename>mac</filename>, <filename>win</filename> and
<filename>compat</filename> subdirectories were eliminated before
the import</para>
distributed by the maintainers of this package. Parts that are entirely
not applicable for FreeBSD can be removed. In the case of Tcl, the
<filename>mac</filename>, <filename>win</filename> and
<filename>compat</filename> subdirectories were eliminated before the
import</para>
<para><filename>src/lib/libtcl</filename> contains only a "bmake style"
<filename>Makefile</filename> that uses the standard
<filename>bsd.lib.mk</filename> makefile rules to produce the
library and install the documentation.</para>
<filename>bsd.lib.mk</filename> makefile rules to produce the library
and install the documentation.</para>
<para><filename>src/usr.bin/tclsh</filename> contains only a bmake style
<filename>Makefile</filename> which will produce and install the
<command>tclsh</command> program and its associated man-pages using the standard
<filename>bsd.prog.mk</filename> rules.</para>
<command>tclsh</command> program and its associated man-pages using the
standard <filename>bsd.prog.mk</filename> rules.</para>
<para><filename>src/tools/tools/tcl_bmake</filename> contains a couple of
shell-scripts that can be of help when the tcl software needs
updating. These are not part of the built or installed
software.</para>
shell-scripts that can be of help when the tcl software needs updating.
These are not part of the built or installed software.</para>
<para>The important thing here is that the
<filename>src/contrib/tcl</filename> directory is created according
to the rules: It is supposed to contain the sources as distributed
(on a proper CVS vendor-branch and without RCS keyword expansion) with as few FreeBSD-specific changes
as possible. The 'easy-import' tool on freefall will assist in
doing the import, but if there are any doubts on how to go about it,
it is imperative that you ask first and not blunder ahead and hope
it &ldquo;works out&rdquo;. CVS is not forgiving of import accidents and a fair
amount of effort is required to back out major mistakes.</para>
<filename>src/contrib/tcl</filename> directory is created according to
the rules: It is supposed to contain the sources as distributed (on a
proper CVS vendor-branch and without RCS keyword expansion) with as few
FreeBSD-specific changes as possible. The 'easy-import' tool on
freefall will assist in doing the import, but if there are any doubts on
how to go about it, it is imperative that you ask first and not blunder
ahead and hope it &ldquo;works out&rdquo;. CVS is not forgiving of
import accidents and a fair amount of effort is required to back out
major mistakes.</para>
<para>Because of the previously mentioned design limitations with CVS's vendor
branches, it is required that &ldquo;official&rdquo; patches from the vendor be
applied to the original distributed sources and the result
re-imported onto the vendor branch again. Official patches should
never be patched into the FreeBSD checked out version and
"committed", as this destroys the vendor branch coherency and makes
importing future versions rather difficult as there will be
conflicts.</para>
<para>Because of the previously mentioned design limitations with CVS's
vendor branches, it is required that &ldquo;official&rdquo; patches from
the vendor be applied to the original distributed sources and the result
re-imported onto the vendor branch again. Official patches should never
be patched into the FreeBSD checked out version and "committed", as this
destroys the vendor branch coherency and makes importing future versions
rather difficult as there will be conflicts.</para>
<para>Since many packages contain files that are meant for
compatibility with other architectures and environments that
FreeBSD, it is permissible to remove parts of the distribution tree
that are of no interest to FreeBSD in order to save space. Files
containing copyright notices and release-note kind of information
applicable to the remaining files shall <emphasis>not</emphasis> be
removed.</para>
<para>Since many packages contain files that are meant for compatibility
with other architectures and environments that FreeBSD, it is
permissible to remove parts of the distribution tree that are of no
interest to FreeBSD in order to save space. Files containing copyright
notices and release-note kind of information applicable to the remaining
files shall <emphasis>not</emphasis> be removed.</para>
<para>If it seems easier, the <command>bmake</command> <filename>Makefile</filename>s
can be produced from the dist tree automatically by some utility,
something which would hopefully make it even easier to upgrade to a
new version. If this is done, be sure to check in such utilities
(as necessary) in the <filename>src/tools</filename> directory along
with the port itself so that it is available to future
maintainers.</para>
<para>In the <filename>src/contrib/tcl</filename> level directory, a
file called <filename>FREEBSD-upgrade</filename> should be added and
it should states things like:</para>
<para>If it seems easier, the <command>bmake</command>
<filename>Makefile</filename>s can be produced from the dist tree
automatically by some utility, something which would hopefully make it
even easier to upgrade to a new version. If this is done, be sure to
check in such utilities (as necessary) in the
<filename>src/tools</filename> directory along with the port itself so
that it is available to future maintainers.</para>
<para>In the <filename>src/contrib/tcl</filename> level directory, a file
called <filename>FREEBSD-upgrade</filename> should be added and it
should states things like:</para>
<itemizedlist>
<listitem>
<para>Which files have been left out</para>
</listitem>
<listitem>
<para>Where the original distribution was obtained from and/or
the official master site.</para>
<para>Where the original distribution was obtained from and/or the
official master site.</para>
</listitem>
<listitem>
@ -170,18 +162,15 @@ MAINTAINER= email-addresses</programlisting>
</listitem>
<listitem>
<para>Perhaps an overview of the FreeBSD-specific changes that
have been made.</para>
<para>Perhaps an overview of the FreeBSD-specific changes that have
been made.</para>
</listitem>
</itemizedlist>
<para>However, please do not import
<filename>FREEBSD-upgrade</filename> with the contributed source.
Rather you should <command>cvs add FREEBSD-upgrade ; cvs ci</command> after the
initial import. Example wording from
<filename>src/contrib/cpio</filename> is below:</para>
<para>However, please do not import <filename>FREEBSD-upgrade</filename>
with the contributed source. Rather you should <command>cvs add
FREEBSD-upgrade ; cvs ci</command> after the initial import. Example
wording from <filename>src/contrib/cpio</filename> is below:</para>
<programlisting>
This directory contains virgin sources of the original distribution files
@ -222,78 +211,74 @@ All local changes should be submitted to "cpio@gnu.ai.mit.edu" for
inclusion in the next vendor release.
obrien@freebsd.org - 30 March 1997</programlisting>
</sect1>
<sect1 id="policies-shlib">
<title>Shared Libraries</title>
<para><emphasis>Contributed by &a.asami;, &a.peter;, and
&a.obrien;.<!-- <br> --> 9 December 1996.</emphasis></para>
<para><emphasis>Contributed by &a.asami;, &a.peter;, and &a.obrien;.<!--
<br> --> 9 December 1996.</emphasis></para>
<para>If you are adding shared library support to a port or other
piece of software that doesn't have one, the version numbers should
follow these rules. Generally, the resulting numbers will have
nothing to do with the release version of the software.</para>
<para>If you are adding shared library support to a port or other piece of
software that doesn't have one, the version numbers should follow these
rules. Generally, the resulting numbers will have nothing to do with
the release version of the software.</para>
<para>The three principles of shared library building are:</para>
<itemizedlist>
<listitem>
<para>Start from <literal>1.0</literal></para>
</listitem>
<listitem>
<para>If there is a change that is backwards compatible, bump
minor number</para>
</listitem>
<listitem>
<para>If there is an incompatible change, bump major
<para>If there is a change that is backwards compatible, bump minor
number</para>
</listitem>
<listitem>
<para>If there is an incompatible change, bump major number</para>
</listitem>
</itemizedlist>
<para>For instance, added functions and bugfixes result in the minor
version number being bumped, while deleted functions, changed
function call syntax etc. will force the major version number to
change.</para>
version number being bumped, while deleted functions, changed function
call syntax etc. will force the major version number to change.</para>
<para>Stick to version numbers of the form major.minor (<replaceable>x</replaceable>.<replaceable>y</replaceable>). Our
dynamic linker does not handle version numbers of the form <replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable>
well. Any version number after the <replaceable>y</replaceable> (ie. the third digit) is
totally ignored when comparing shared lib version numbers to decide
which library to link with. Given two shared libraries that differ
only in the &ldquo;micro&rdquo; revision, <command>ld.so</command> will link with the higher one.
Ie: if you link with <filename>libfoo.so.3.3.3</filename>, the
linker only records <literal>3.3</literal> in the headers, and will link with anything
starting with <replaceable>libfoo.so.3</replaceable>.<replaceable>(anything &gt;=
3)</replaceable>.<replaceable>(highest available)</replaceable>.</para>
<para>Stick to version numbers of the form major.minor
(<replaceable>x</replaceable>.<replaceable>y</replaceable>). Our
dynamic linker does not handle version numbers of the form
<replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable>
well. Any version number after the <replaceable>y</replaceable>
(ie. the third digit) is totally ignored when comparing shared lib
version numbers to decide which library to link with. Given two shared
libraries that differ only in the &ldquo;micro&rdquo; revision,
<command>ld.so</command> will link with the higher one. Ie: if you link
with <filename>libfoo.so.3.3.3</filename>, the linker only records
<literal>3.3</literal> in the headers, and will link with anything
starting with
<replaceable>libfoo.so.3</replaceable>.<replaceable>(anything &gt;=
3)</replaceable>.<replaceable>(highest
available)</replaceable>.</para>
<note>
<para><command>ld.so</command> will always use the highest
&ldquo;minor&rdquo; revision. Ie: it will use <filename>libc.so.2.2</filename>
in preference to <filename>libc.so.2.0</filename>, even if the
program was initially linked with
<filename>libc.so.2.0</filename>.</para>
&ldquo;minor&rdquo; revision. Ie: it will use
<filename>libc.so.2.2</filename> in preference to
<filename>libc.so.2.0</filename>, even if the program was initially
linked with <filename>libc.so.2.0</filename>.</para>
</note>
<para>For non-port libraries, it is also our policy to change the
shared library version number only once between releases. When you
make a change to a system library that requires the version number
to be bumped, check the <filename>Makefile</filename>'s commit logs.
It is the responsibility of the committer to ensure that the first
such change since the release will result in the shared library
version number in the <filename>Makefile</filename> to be updated,
and any subsequent changes will not.</para>
<para>For non-port libraries, it is also our policy to change the shared
library version number only once between releases. When you make a
change to a system library that requires the version number to be
bumped, check the <filename>Makefile</filename>'s commit logs. It is the
responsibility of the committer to ensure that the first such change
since the release will result in the shared library version number in
the <filename>Makefile</filename> to be updated, and any subsequent
changes will not.</para>
</sect1>
</chapter>
</chapter>
<!--
Local Variables:

3195
en_US.ISO8859-1/books/handbook/ports/chapter.sgml
View file

File diff suppressed because it is too large Load diff

1700
en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.sgml
View file

File diff suppressed because it is too large Load diff

4150
en_US.ISO8859-1/books/handbook/printing/chapter.sgml
View file

File diff suppressed because it is too large Load diff

1468
en_US.ISO8859-1/books/handbook/security/chapter.sgml
View file

File diff suppressed because it is too large Load diff

1788
en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml
View file

File diff suppressed because it is too large Load diff

173
en_US.ISO8859-1/books/handbook/staff/chapter.sgml
View file

@ -1,9 +1,8 @@
<chapter id="staff">
<chapter id="staff">
<title>FreeBSD Project Staff</title>
<para>The FreeBSD Project is managed and operated by the following
groups of people:</para>
<para>The FreeBSD Project is managed and operated by the following groups of
people:</para>
<sect1 id="staff-core">
<title>The FreeBSD Core Team</title>
@ -15,9 +14,7 @@
<para>(in alphabetical order by last name):</para>
<itemizedlist>
<listitem>
<para>&a.asami;</para>
</listitem>
@ -77,19 +74,15 @@
<listitem>
<para>&a.joerg;</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="staff-committers">
<title>The FreeBSD Developers</title>
<para>These are the people who have commit privileges and do the
engineering work on the FreeBSD source tree. All core team members
are also developers.</para>
engineering work on the FreeBSD source tree. All core team members are
also developers.</para>
<itemizedlist>
<listitem>
@ -579,52 +572,49 @@
<listitem>
<para>&a.archie;</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="staff-doc">
<title>The FreeBSD Documentation Project</title>
<para>The <ulink URL="http://www.freebsd.org/docproj.html">FreeBSD
Documentation Project</ulink> is responsible for a number of
different services, each service being run by an individual and his
Documentation Project</ulink> is responsible for a number of different
services, each service being run by an individual and his
<emphasis>deputies</emphasis> (if any):</para>
<variablelist>
<varlistentry><term>Documentation Project Manager</term>
<varlistentry>
<term>Documentation Project Manager</term>
<listitem>
<para>&a.nik;</para>
</listitem>
</varlistentry>
<varlistentry><term>Webmaster</term>
<varlistentry>
<term>Webmaster</term>
<listitem>
<para>&a.wosch;</para>
</listitem>
</varlistentry>
<varlistentry><term>Handbook &amp; FAQ Editor</term>
<varlistentry>
<term>Handbook &amp; FAQ Editor</term>
<listitem>
<para>&a.faq;</para>
</listitem>
</varlistentry>
<varlistentry><term>News Editor</term>
<varlistentry>
<term>News Editor</term>
<listitem>
<para>&a.nsj;</para>
<para><emphasis>Deputy:</emphasis> &a.john;</para>
</listitem>
</varlistentry>
@ -636,7 +626,8 @@
</listitem>
</varlistentry>
<varlistentry><term>Gallery Editor</term>
<varlistentry>
<term>Gallery Editor</term>
<listitem>
<para>&a.nsj;</para>
@ -662,28 +653,32 @@
</listitem>
</varlistentry>
<varlistentry><term>Style Police &amp; Art Director</term>
<varlistentry>
<term>Style Police &amp; Art Director</term>
<listitem>
<para>&a.opsys;</para>
</listitem>
</varlistentry>
<varlistentry><term>Database Engineer</term>
<varlistentry>
<term>Database Engineer</term>
<listitem>
<para>&a.mayo;</para>
</listitem>
</varlistentry>
<varlistentry><term>CGI Engineer</term>
<varlistentry>
<term>CGI Engineer</term>
<listitem>
<para>&a.stb;</para>
</listitem>
</varlistentry>
<varlistentry><term>Bottle Washing</term>
<varlistentry>
<term>Bottle Washing</term>
<listitem>
<para>&a.nsj;</para>
@ -698,36 +693,35 @@
</listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="staff-who">
<title>Who Is Responsible for What</title>
<variablelist>
<varlistentry><term>Principal Architect</term>
<varlistentry>
<term>Principal Architect</term>
<listitem>
<para>&a.dg;</para>
</listitem>
</varlistentry>
<varlistentry><term><ulink
url="http://www.freebsd.org/docproj/docproj.html">Documentation Project Manager</ulink></term>
<varlistentry>
<term><ulink
url="http://www.freebsd.org/docproj/docproj.html">Documentation
Project Manager</ulink></term>
<listitem>
<para>&a.nik;</para>
</listitem>
</varlistentry>
<varlistentry><term><link linkend="l10n">Internationalization</link></term>
<varlistentry>
<term><link linkend="l10n">Internationalization</link></term>
<listitem>
<para>&a.ache;</para>
</listitem>
</varlistentry>
@ -735,44 +729,45 @@
<listitem>
<para>&a.wollman;</para>
</listitem>
</varlistentry>
<varlistentry><term><link linkend="eresources-mail">Postmaster</link></term>
<varlistentry>
<term><link linkend="eresources-mail">Postmaster</link></term>
<listitem>
<para>&a.jmb;</para>
</listitem>
</varlistentry>
<varlistentry><term>Release Coordinator</term>
<varlistentry>
<term>Release Coordinator</term>
<listitem>
<para>&a.jkh;</para>
</listitem>
</varlistentry>
<varlistentry><term>Public Relations &amp; Corporate
Liaison</term>
<varlistentry>
<term>Public Relations &amp; Corporate Liaison</term>
<listitem>
<para>&a.jkh;</para>
</listitem>
</varlistentry>
<varlistentry><term><ulink url="http://www.freebsd.org/security/">Security Officer</ulink></term>
<varlistentry>
<term><ulink url="http://www.freebsd.org/security/">Security
Officer</ulink></term>
<listitem>
<para>&a.imp;</para>
</listitem>
</varlistentry>
<varlistentry><term><ulink url="http://www.freebsd.org/support.html#cvs">>Source Repository Managers</ulink></term>
<varlistentry>
<term><ulink url="http://www.freebsd.org/support.html#cvs">>Source
Repository Managers</ulink></term>
<listitem>
<para>Principal: &a.peter;</para>
@ -780,54 +775,54 @@
<para>Assistant: &a.jdp;</para>
<para>International (Crypto): &a.markm;</para>
</listitem>
</varlistentry>
<varlistentry><term><ulink url="http://www.freebsd.org/ports/">Ports Manager</ulink></term>
<listitem>
<para>&a.asami;</para>
</listitem>
</varlistentry>
<varlistentry><term>XFree86 Project, Inc. Liaison</term>
<listitem>
<para>&a.rich;</para>
</listitem>
</varlistentry>
<varlistentry><term><link linkend="eresources-news">Usenet Support</link></term>
<listitem>
<para>&a.joerg;</para>
</listitem>
</varlistentry>
<varlistentry><term><ulink url="http://www.freebsd.org/support.html#gnats">GNATS Administrator</ulink></term>
<listitem>
<para>&a.steve;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url="http://www.freebsd.org/internal/">Webmaster</ulink></term>
<term><ulink url="http://www.freebsd.org/ports/">Ports
Manager</ulink></term>
<listitem>
<para>&a.asami;</para>
</listitem>
</varlistentry>
<varlistentry>
<term>XFree86 Project, Inc. Liaison</term>
<listitem>
<para>&a.rich;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><link linkend="eresources-news">Usenet Support</link></term>
<listitem>
<para>&a.joerg;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url="http://www.freebsd.org/support.html#gnats">GNATS
Administrator</ulink></term>
<listitem>
<para>&a.steve;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink
url="http://www.freebsd.org/internal/">Webmaster</ulink></term>
<listitem>
<para>&a.wosch;</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
</chapter>
</chapter>
<!--
Local Variables:

11
en_US.ISO8859-1/books/handbook/x11/chapter.sgml
View file

@ -1,11 +1,10 @@
<chapter id="x11">
<chapter id="x11">
<title>The X Window System</title>
<para>Pending the completion of this section, please refer to
documentation supplied by the <ulink URL="http://www.xfree86.org/">The
XFree86 Project, Inc</ulink>.</para>
</chapter>
<para>Pending the completion of this section, please refer to documentation
supplied by the <ulink URL="http://www.xfree86.org/">The XFree86 Project,
Inc</ulink>.</para>
</chapter>
<!--
Local Variables:

3195
en_US.ISO8859-1/books/porters-handbook/book.sgml
View file

File diff suppressed because it is too large Load diff

835
en_US.ISO_8859-1/books/handbook/advanced-networking/chapter.sgml
View file

File diff suppressed because it is too large Load diff

265
en_US.ISO_8859-1/books/handbook/backups/chapter.sgml
View file

@ -9,10 +9,10 @@
impossible to provide a exhaustive listing of hardware that FreeBSD
supports, this section serves as a catalog of the device drivers included
with FreeBSD and the hardware each drivers supports. Where possible and
appropriate, notes about specific products are included. You may also want
to refer to <link linkend="kernelconfig-config"> the kernel configuration
file</link> section in this handbook for a list of supported
devices.</para>
appropriate, notes about specific products are included. You may also
want to refer to <link linkend="kernelconfig-config"> the kernel
configuration file</link> section in this handbook for a list of
supported devices.</para>
<para>As FreeBSD is a volunteer project without a funded testing department,
we depend on you, the user, for much of the information contained in this
@ -37,8 +37,7 @@
DLT.</para>
<sect2 id="backups-tapebackups-4mm">
<title>4mm (DDS: Digital Data
Storage)</title>
<title>4mm (DDS: Digital Data Storage)</title>
<para>4mm tapes are replacing QIC as the workstation backup media of
choice. This trend accelerated greatly when Conner purchased Archive,
@ -52,9 +51,9 @@
<para>Data thruput on these drives starts ~150kB/s, peaking at ~500kB/s.
Data capacity starts at 1.3 GB and ends at 2.0 GB. Hardware
compression, available with most of these drives, approximately
doubles the capacity. Multi-drive tape library units can have 6 drives
in a single cabinet with automatic tape changing. Library capacities
reach 240 GB.</para>
doubles the capacity. Multi-drive tape library units can have 6
drives in a single cabinet with automatic tape changing. Library
capacities reach 240 GB.</para>
<para>4mm drives, like 8mm drives, use helical-scan. All the benefits
and drawbacks of helical-scan apply to both 4mm and 8mm drives.</para>
@ -73,19 +72,19 @@
One downside of 8mm tape is relatively short head and tape life due to
the high rate of relative motion of the tape across the heads.</para>
<para>Data thruput ranges from ~250kB/s to ~500kB/s. Data sizes start at
300 MB and go up to 7 GB. Hardware compression, available with most of
these drives, approximately doubles the capacity. These drives are
available as single units or multi-drive tape libraries with 6 drives
and 120 tapes in a single cabinet. Tapes are changed automatically by
the unit. Library capacities reach 840+ GB.</para>
<para>Data thruput ranges from ~250kB/s to ~500kB/s. Data sizes start
at 300 MB and go up to 7 GB. Hardware compression, available with
most of these drives, approximately doubles the capacity. These
drives are available as single units or multi-drive tape libraries
with 6 drives and 120 tapes in a single cabinet. Tapes are changed
automatically by the unit. Library capacities reach 840+ GB.</para>
<para>Data is recorded onto the tape using helical-scan, the heads are
positioned at an angle to the media (approximately 6 degrees). The
tape wraps around 270 degrees of the spool that holds the heads. The
spool spins while the tape slides over the spool. The result is a high
density of data and closely packed tracks that angle across the tape
from one edge to the other.</para>
spool spins while the tape slides over the spool. The result is a
high density of data and closely packed tracks that angle across the
tape from one edge to the other.</para>
</sect2>
<sect2 id="backups-tapebackups-qic">
@ -100,21 +99,22 @@
<emphasis>most</emphasis> common tape drive. Every site has a QIC
drive of some density or another. Therein lies the rub, QIC has a
large number of densities on physically similar (sometimes identical)
tapes. QIC drives are not quiet. These drives audibly seek before they
begin to record data and are clearly audible whenever reading, writing
or seeking. QIC tapes measure (6 x 4 x 0.7 inches; 15.2 x 10.2 x 1.7
mm). <link linkend="backups-tapebackups-mini">Mini-cartridges</link>,
which also use 1/4" wide tape are discussed separately. Tape libraries
and changers are not available.</para>
tapes. QIC drives are not quiet. These drives audibly seek before
they begin to record data and are clearly audible whenever reading,
writing or seeking. QIC tapes measure (6 x 4 x 0.7 inches; 15.2 x
10.2 x 1.7 mm). <link
linkend="backups-tapebackups-mini">Mini-cartridges</link>, which
also use 1/4" wide tape are discussed separately. Tape libraries and
changers are not available.</para>
<para>Data thruput ranges from ~150kB/s to ~500kB/s. Data capacity
ranges from 40 MB to 15 GB. Hardware compression is available on many
of the newer QIC drives. QIC drives are less frequently installed;
they are being supplanted by DAT drives.</para>
<para>Data is recorded onto the tape in tracks. The tracks run along the
long axis of the tape media from one end to the other. The number of
tracks, and therefore the width of a track, varies with the tape's
<para>Data is recorded onto the tape in tracks. The tracks run along
the long axis of the tape media from one end to the other. The number
of tracks, and therefore the width of a track, varies with the tape's
capacity. Most if not all newer drives provide backward-compatibility
at least for reading (but often also for writing). QIC has a good
reputation regarding the safety of the data (the mechanics are simpler
@ -160,15 +160,13 @@
<sect2>
<title>Using a new tape for the first time</title>
<para>The first time that you try to read or write a new,
completely blank tape, the operation will fail. The console
messages should be similar to:</para>
<para>The first time that you try to read or write a new, completely
blank tape, the operation will fail. The console messages should be
similar to:</para>
<screen>st0(ncr1:4:0): NOT READY asc:4,1
st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
<para>The tape does not contain an Identifier Block (block number 0).
All QIC tape drives since the adoption of QIC-525 standard write an
Identifier Block to the tape. There are two solutions:</para>
@ -178,12 +176,11 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
<para>Use the front panel button to eject the tape.</para>
<para>Re-insert the tape and
&man.dump.8; data to the tape.</para>
<para>Re-insert the tape and &man.dump.8; data to the tape.</para>
<para>&man.dump.8; will report <literal>DUMP:
End of tape detected</literal> and the console will show:
<literal>HARDWARE FAILURE info:280 asc:80,96</literal></para>
<para>&man.dump.8; will report <literal>DUMP: End of tape
detected</literal> and the console will show: <literal>HARDWARE
FAILURE info:280 asc:80,96</literal></para>
<para>rewind the tape using: <command>mt rewind</command></para>
@ -203,84 +200,81 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
<sect2>
<title>Dump and Restore</title>
<para>&man.dump.8; and &man.restore.8; are the traditional Unix backup programs. They operate
on the drive as a collection of disk blocks, below the abstractions of
files, links and directories that are created by the filesystems.
&man.dump.8; backs up devices, entire filesystems, not parts of a
filesystem and not directory trees that span more than one filesystem,
using either soft links &man.ln.1; or mounting one filesystem onto another.
&man.dump.8; does not write files and directories to tape, but
rather writes the data blocks that are the building blocks of files
and directories. &man.dump.8; has quirks that remain from its early days in
Version 6 of ATT Unix (circa 1975). The default parameters are
suitable for 9-track tapes (6250 bpi), not the high-density media
available today (up to 62,182 ftpi). These defaults must be overridden
on the command line to utilize the capacity of current tape
drives.</para>
<para>&man.dump.8; and &man.restore.8; are the traditional Unix backup
programs. They operate on the drive as a collection of disk blocks,
below the abstractions of files, links and directories that are
created by the filesystems. &man.dump.8; backs up devices, entire
filesystems, not parts of a filesystem and not directory trees that
span more than one filesystem, using either soft links &man.ln.1; or
mounting one filesystem onto another. &man.dump.8; does not write
files and directories to tape, but rather writes the data blocks that
are the building blocks of files and directories. &man.dump.8; has
quirks that remain from its early days in Version 6 of ATT Unix (circa
1975). The default parameters are suitable for 9-track tapes (6250
bpi), not the high-density media available today (up to 62,182 ftpi).
These defaults must be overridden on the command line to utilize the
capacity of current tape drives.</para>
<para>&man.rdump.8; and &man.rrestore.8; backup data across the
network to a tape drive attached to another computer. Both programs
rely upon &man.rcmd.3; and &man.ruserok.3; to access the remote tape
drive. Therefore, the user performing the backup must have
<para>&man.rdump.8; and &man.rrestore.8; backup data across the network
to a tape drive attached to another computer. Both programs rely upon
&man.rcmd.3; and &man.ruserok.3; to access the remote tape drive.
Therefore, the user performing the backup must have
<literal>rhosts</literal> access to the remote computer. The
arguments to &man.rdump.8; and &man.rrestore.8; must suitable to use on the remote computer. (e.g.
When <command>rdump</command>'ing from a FreeBSD computer to an
Exabyte tape drive connected to a Sun called
<hostid>komodo</hostid>, use: <command>/sbin/rdump 0dsbfu 54000
13000 126 komodo:/dev/nrst8 /dev/rsd0a 2>&amp;1</command>) Beware:
there are security implications to allowing <literal>rhosts</literal>
arguments to &man.rdump.8; and &man.rrestore.8; must suitable to use
on the remote computer. (e.g. When <command>rdump</command>'ing from
a FreeBSD computer to an Exabyte tape drive connected to a Sun called
<hostid>komodo</hostid>, use: <command>/sbin/rdump 0dsbfu 54000 13000
126 komodo:/dev/nrst8 /dev/rsd0a 2>&amp;1</command>) Beware: there
are security implications to allowing <literal>rhosts</literal>
commands. Evaluate your situation carefully.</para>
</sect2>
<sect2>
<title>Tar</title>
<para>&man.tar.1; also dates back to Version 6 of ATT Unix (circa
1975). &man.tar.1; operates in cooperation with the filesystem;
&man.tar.1; writes files and directories to tape.
&man.tar.1; does not support the full range of options that are
available from &man.cpio.1;, but &man.tar.1; does not require the
unusual command pipeline that &man.cpio.1; uses.</para>
<para>&man.tar.1; also dates back to Version 6 of ATT Unix (circa 1975).
&man.tar.1; operates in cooperation with the filesystem; &man.tar.1;
writes files and directories to tape. &man.tar.1; does not support the
full range of options that are available from &man.cpio.1;, but
&man.tar.1; does not require the unusual command pipeline that
&man.cpio.1; uses.</para>
<para>Most versions of &man.tar.1; do not support backups across the network. The GNU
version of &man.tar.1;, which FreeBSD utilizes,
supports remote devices using the same syntax as
&man.rdump.8;. To &man.tar.1; to an Exabyte tape drive connected to a Sun called
<hostid>komodo</hostid>, use: <command>/usr/bin/tar cf komodo:/dev/nrst8 .
2>&amp;1</command>. For versions without remote device support,
you can use a pipeline and &man.rsh.1; to send the data to a
remote tape drive. (XXX add an example command)</para>
<para>Most versions of &man.tar.1; do not support backups across the
network. The GNU version of &man.tar.1;, which FreeBSD utilizes,
supports remote devices using the same syntax as &man.rdump.8;. To
&man.tar.1; to an Exabyte tape drive connected to a Sun called
<hostid>komodo</hostid>, use: <command>/usr/bin/tar cf
komodo:/dev/nrst8 . 2>&amp;1</command>. For versions without remote
device support, you can use a pipeline and &man.rsh.1; to send the
data to a remote tape drive. (XXX add an example command)</para>
</sect2>
<sect2>
<title>Cpio</title>
<para>&man.cpio.1; is the original Unix
file interchange tape program for magnetic media. &man.cpio.1; has options (among many
others) to perform byte-swapping, write a number of different
archives format, and pipe the data to other programs. This last
feature makes &man.cpio.1; and excellent choice for
installation media. &man.cpio.1; does not know how to walk
the directory tree and a list of files must be provided thru
<filename>STDIN</filename>.</para>
<para>&man.cpio.1; is the original Unix file interchange tape program
for magnetic media. &man.cpio.1; has options (among many others) to
perform byte-swapping, write a number of different archives format,
and pipe the data to other programs. This last feature makes
&man.cpio.1; and excellent choice for installation media.
&man.cpio.1; does not know how to walk the directory tree and a list
of files must be provided thru <filename>STDIN</filename>.</para>
<para>&man.cpio.1; does not support backups
across the network. You can use a pipeline and &man.rsh.1; to send the data to a
remote tape drive. (XXX add an example command)</para>
<para>&man.cpio.1; does not support backups across the network. You can
use a pipeline and &man.rsh.1; to send the data to a remote tape
drive. (XXX add an example command)</para>
</sect2>
<sect2>
<title>Pax</title>
<para>&man.pax.1; is IEEE/POSIX's answer to
&man.tar.1; and &man.cpio.1;. Over the years the
various versions of &man.tar.1; and &man.cpio.1;
have gotten slightly incompatible. So rather than fight it out to
fully standardize them, POSIX created a new archive utility.
&man.pax.1; attempts to read and write many of the various
&man.cpio.1; and &man.tar.1; formats, plus new formats of its own. Its command set
more resembles &man.cpio.1; than
&man.tar.1;.</para>
<para>&man.pax.1; is IEEE/POSIX's answer to &man.tar.1; and
&man.cpio.1;. Over the years the various versions of &man.tar.1;
and &man.cpio.1; have gotten slightly incompatible. So rather than
fight it out to fully standardize them, POSIX created a new archive
utility. &man.pax.1; attempts to read and write many of the various
&man.cpio.1; and &man.tar.1; formats, plus new formats of its own.
Its command set more resembles &man.cpio.1; than &man.tar.1;.</para>
</sect2>
<sect2 id="backups-programs-amanda">
@ -290,9 +284,9 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
(Advanced Maryland Network Disk Archiver) is a client/server backup
system, rather than a single program. An Amanda server will backup to
a single tape drive any number of computers that have Amanda clients
and network communications with the Amanda server. A common problem at
locations with a number of large disks is the length of time required
to backup to data directly to tape exceeds the amount of time
and network communications with the Amanda server. A common problem
at locations with a number of large disks is the length of time
required to backup to data directly to tape exceeds the amount of time
available for the task. Amanda solves this problem. Amanda can use a
"holding disk" to backup several filesystems at the same time. Amanda
creates "archive sets": a group of tapes used over a period of time to
@ -312,9 +306,9 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
<title>Do nothing</title>
<para>&ldquo;Do nothing&rdquo; is not a computer program, but it is the
most widely used backup strategy. There are no initial costs. There is
no backup schedule to follow. Just say no. If something happens to
your data, grin and bear it!</para>
most widely used backup strategy. There are no initial costs. There
is no backup schedule to follow. Just say no. If something happens
to your data, grin and bear it!</para>
<para>If your time and your data is worth little to nothing, then
&ldquo;Do nothing&rdquo; is the most suitable backup program for your
@ -334,19 +328,20 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
<sect2>
<title>Which Backup Program is Best?</title>
<para>&man.dump.8; <emphasis>Period.</emphasis>
Elizabeth D. Zwicky torture tested all the backup programs discussed
here. The clear choice for preserving all your data and all the
peculiarities of Unix filesystems is &man.dump.8;. Elizabeth created
filesystems containing a large variety of unusual conditions (and some
not so unusual ones) and tested each program by do a backup and
restore of that filesystems. The peculiarities included: files with
holes, files with holes and a block of nulls, files with funny
characters in their names, unreadable and unwritable files, devices,
files that change size during the backup, files that are
created/deleted during the backup and more. She presented the results
at LISA V in Oct. 1991. See <ulink
url="http://reality.sgi.com/zwicky_neu/testdump.doc.html">torture-testing Backup and Archive Programs</ulink>.</para>
<para>&man.dump.8; <emphasis>Period.</emphasis> Elizabeth D. Zwicky
torture tested all the backup programs discussed here. The clear
choice for preserving all your data and all the peculiarities of Unix
filesystems is &man.dump.8;. Elizabeth created filesystems containing
a large variety of unusual conditions (and some not so unusual ones)
and tested each program by do a backup and restore of that
filesystems. The peculiarities included: files with holes, files with
holes and a block of nulls, files with funny characters in their
names, unreadable and unwritable files, devices, files that change
size during the backup, files that are created/deleted during the
backup and more. She presented the results at LISA V in Oct. 1991.
See <ulink
url="http://reality.sgi.com/zwicky_neu/testdump.doc.html">torture-testing
Backup and Archive Programs</ulink>.</para>
</sect2>
<sect2>
@ -370,12 +365,12 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
messages. If all your devices are listed and functional, skip on to
step three.</para>
<para>Otherwise, you have to create two custom bootable floppies
which has a kernel that can mount your all of your disks and
access your tape drive. These floppies must contain:
&man.fdisk.8;, &man.disklabel.8;, &man.newfs.8;, &man.mount.8;, and whichever backup
program you use. These programs must be statically linked. If you
use &man.dump.8;, the floppy must contain
<para>Otherwise, you have to create two custom bootable floppies which
has a kernel that can mount your all of your disks and access your
tape drive. These floppies must contain:
&man.fdisk.8;, &man.disklabel.8;, &man.newfs.8;, &man.mount.8;, and
whichever backup program you use. These programs must be statically
linked. If you use &man.dump.8;, the floppy must contain
&man.restore.8;.</para>
<para>Third, create backup tapes regularly. Any changes that you make
@ -385,19 +380,19 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
<para>Fourth, test the floppies (either <filename>boot.flp</filename>
and <filename>fixit.flp</filename> or the two custom bootable
floppies you made in step two.) and backup tapes. Make notes of the
procedure. Store these notes with the bootable floppy, the printouts
and the backup tapes. You will be so distraught when restoring that
the notes may prevent you from destroying your backup tapes (How?
In place of <command>tar xvf /dev/rst0</command>, you might
accidently type <command>tar cvf /dev/rst0</command> and over-write
your backup tape).</para>
procedure. Store these notes with the bootable floppy, the
printouts and the backup tapes. You will be so distraught when
restoring that the notes may prevent you from destroying your backup
tapes (How? In place of <command>tar xvf /dev/rst0</command>, you
might accidently type <command>tar cvf /dev/rst0</command> and
over-write your backup tape).</para>
<para>For an added measure of security, make bootable floppies and two
backup tapes each time. Store one of each at a remote location. A
remote location is NOT the basement of the same office building. A
number of firms in the World Trade Center learned this lesson the
hard way. A remote location should be physically separated from your
computers and disk drives by a significant distance.</para>
hard way. A remote location should be physically separated from
your computers and disk drives by a significant distance.</para>
<para>An example script for creating a bootable floppy:</para>
@ -586,13 +581,13 @@ chmod 644 /mnt/etc/passwd
/mnt</command>) the root partition of your first disk. If the
disklabel was damaged, use &man.disklabel.8; to re-partition and
label the disk to match the label that your printed and saved. Use
&man.newfs.8; to re-create the
filesystems. Re-mount the root partition of the floppy read-write
(<command>mount -u -o rw /mnt</command>). Use your backup program
and backup tapes to recover the data for this filesystem (e.g.
<command>restore vrf /dev/st0</command>). Unmount the filesystem
(e.g. <command>umount /mnt</command>) Repeat for each filesystem
that was damaged.</para>
&man.newfs.8; to re-create the filesystems. Re-mount the root
partition of the floppy read-write (<command>mount -u -o rw
/mnt</command>). Use your backup program and backup tapes to
recover the data for this filesystem (e.g. <command>restore vrf
/dev/st0</command>). Unmount the filesystem (e.g. <command>umount
/mnt</command>) Repeat for each filesystem that was
damaged.</para>
<para>Once your system is running, backup your data onto new tapes.
Whatever caused the crash or data loss may strike again. An another

89
en_US.ISO_8859-1/books/handbook/basics/chapter.sgml
View file

@ -1,33 +1,27 @@
<chapter id="basics">
<chapter id="basics">
<title>Unix Basics</title>
<sect1 id="basics-man">
<title>The Online Manual</title>
<para>The most comprehensive documentation on FreeBSD is in the form
of <emphasis>man pages</emphasis>. Nearly every program on the
system comes with a short reference manual explaining the basic
operation and various arguments. These manuals can be view with the
<command>man</command>
command. Use of the <command>man</command> command is simple:</para>
<para>The most comprehensive documentation on FreeBSD is in the form of
<emphasis>man pages</emphasis>. Nearly every program on the system
comes with a short reference manual explaining the basic operation and
various arguments. These manuals can be view with the
<command>man</command> command. Use of the <command>man</command>
command is simple:</para>
<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>
<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput>
</screen>
<para><replaceable>command</replaceable> is
the name of the command you wish to learn about. For example, to
learn more about <command>ls</command> command type:</para>
<para><replaceable>command</replaceable> is the name of the command you
wish to learn about. For example, to learn more about
<command>ls</command> command type:</para>
<screen>&prompt.user; <userinput>man ls</userinput></screen>
<para>The online manual is divided up into numbered sections:</para>
<orderedlist>
<listitem>
<para>User commands</para>
</listitem>
@ -59,57 +53,47 @@
<listitem>
<para>System maintenance and operation commands</para>
</listitem>
</orderedlist>
<para>In some cases, the same topic may appear in more than
one section of the on-line manual. For example, there is a
<command>chmod</command>
user command and a <function>chmod()</function> system call. In
this case, you can tell the <command>man</command> command which one you want by
specifying the section:</para>
<para>In some cases, the same topic may appear in more than one section of
the on-line manual. For example, there is a <command>chmod</command>
user command and a <function>chmod()</function> system call. In this
case, you can tell the <command>man</command> command which one you want
by specifying the section:</para>
<screen>&prompt.user; <userinput>man 1 chmod</userinput></screen>
<para>This will display the manual page for the user
command <command>chmod</command>. References to a
particular section of the on-line manual are traditionally placed in
parenthesis in written documentation, so &man.chmod.1; refers to the
<command>chmod</command>
user command and &man.chmod.2; refers to the
<para>This will display the manual page for the user command
<command>chmod</command>. References to a particular section of the
on-line manual are traditionally placed in parenthesis in written
documentation, so &man.chmod.1; refers to the
<command>chmod</command> user command and &man.chmod.2; refers to the
system call.</para>
<para>This is fine if you know the name of the command and simply wish
to know how to use it, but what if you cannot recall the command
name? You can use <command>man</command> to search for keywords in the
command <emphasis>descriptions</emphasis> by using the
<option>-k</option> switch:</para>
<para>This is fine if you know the name of the command and simply wish to
know how to use it, but what if you cannot recall the command name? You
can use <command>man</command> to search for keywords in the command
<emphasis>descriptions</emphasis> by using the <option>-k</option>
switch:</para>
<screen>&prompt.user; <userinput>man -k mail</userinput></screen>
<para>With this command you will be presented with a
list of commands that have the keyword &ldquo;mail&rdquo; in their descriptions.
This is actually functionally equivalent to using the <command>apropos</command>
<para>With this command you will be presented with a list of commands that
have the keyword &ldquo;mail&rdquo; in their descriptions. This is
actually functionally equivalent to using the <command>apropos</command>
command.</para>
<para>So, you are looking at all those fancy commands in
<filename>/usr/bin</filename> but do not even have the faintest idea
what most of them actually do? Simply do a
<screen>&prompt.user; <userinput>cd /usr/bin; man -f *</userinput></screen>
or
<screen>&prompt.user; <userinput>cd /usr/bin; whatis *</userinput></screen>
which does the same thing.</para>
which does the same thing.</para>
</sect1>
<sect1 id="basics-info">
@ -120,20 +104,17 @@
programs come with more extensive hypertext documents called
&ldquo;info&rdquo; files which can be viewed with the
<command>info</command> command or, if you installed
<command>emacs</command>, the info mode of <command>emacs</command>.</para>
<command>emacs</command>, the info mode of
<command>emacs</command>.</para>
<para>To use the &man.info.1; command, simply type:</para>
<screen>&prompt.user; <userinput>info</userinput></screen>
<para>For a brief introduction, type <userinput>h</userinput>. For a quick
command reference, type <userinput>?</userinput>.</para>
<para>For a brief introduction, type <userinput>h</userinput>. For a
quick command reference, type <userinput>?</userinput>.</para>
</sect1>
</chapter>
</chapter>
<!--
Local Variables:

357
en_US.ISO_8859-1/books/handbook/bibliography/chapter.sgml
View file

@ -1,13 +1,11 @@
<chapter id="bibliography">
<chapter id="bibliography">
<title>Bibliography</title>
<para>While the manual pages provide the definitive reference for
individual pieces of the FreeBSD operating system, they are notorious
for not illustrating how to put the pieces together to make the whole
operating system run smoothly. For this, there is no substitute for a
good book on UNIX system administration and a good users'
manual.</para>
<para>While the manual pages provide the definitive reference for individual
pieces of the FreeBSD operating system, they are notorious for not
illustrating how to put the pieces together to make the whole operating
system run smoothly. For this, there is no substitute for a good book on
UNIX system administration and a good users' manual.</para>
<sect1>
<title>Books &amp; Magazines Specific to FreeBSD</title>
@ -15,9 +13,7 @@
<para><emphasis>International books &amp;
Magazines:</emphasis></para>
<itemizedlist>
<listitem>
<para><ulink
URL="http://freebsd.csie.nctu.edu.tw/~jdli/book.html">Using
@ -25,13 +21,13 @@
</listitem>
<listitem>
<para>FreeBSD for PC 98'ers (in Japanese), published by SHUWA
System Co, LTD. ISBN 4-87966-468-5 C3055 P2900E.</para>
<para>FreeBSD for PC 98'ers (in Japanese), published by SHUWA System
Co, LTD. ISBN 4-87966-468-5 C3055 P2900E.</para>
</listitem>
<listitem>
<para>FreeBSD (in Japanese), published by CUTT. ISBN
4-906391-22-2 C3055 P2400E.</para>
<para>FreeBSD (in Japanese), published by CUTT. ISBN 4-906391-22-2
C3055 P2400E.</para>
</listitem>
<listitem>
@ -45,9 +41,9 @@
</listitem>
<listitem>
<para>FreeBSD Handbook (Japanese translation), published by
<ulink URL="http://www.ascii.co.jp/">ASCII</ulink>. ISBN
4-7561-1580-2 P3800E.</para>
<para>FreeBSD Handbook (Japanese translation), published by <ulink
URL="http://www.ascii.co.jp/">ASCII</ulink>. ISBN 4-7561-1580-2
P3800E.</para>
</listitem>
<listitem>
@ -56,179 +52,157 @@
</listitem>
<listitem>
<para><ulink url="http://www.pc.mycom.co.uk/FreeBSD/install-manual.html">FreeBSD
Install and Utilization Manual</ulink> (in Japanese),
published by <ulink url="http://www.pc.mycom.co.jp/">Mainichi
Communications Inc.</ulink>.</para>
<para><ulink
url="http://www.pc.mycom.co.uk/FreeBSD/install-manual.html">FreeBSD Install and Utilization Manual</ulink> (in Japanese), published by <ulink url="http://www.pc.mycom.co.jp/">Mainichi Communications Inc.</ulink>.</para>
</listitem>
</itemizedlist>
<para><emphasis>English language books &amp;
Magazines:</emphasis></para>
<para><emphasis>English language books &amp; Magazines:</emphasis></para>
<itemizedlist>
<listitem>
<para><ulink
URL="http://www.cdrom.com/titles/freebsd/bsdbook2.htm">The
Complete FreeBSD</ulink>, published by <ulink
URL="http://www.cdrom.com">Walnut Creek
CDROM</ulink>.</para>
URL="http://www.cdrom.com">Walnut Creek CDROM</ulink>.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>Users' Guides</title>
<itemizedlist>
<listitem>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD User's Reference Manual</emphasis>. O'Reilly
&amp; Associates, Inc., 1994.<!-- <br> --> ISBN
1-56592-075-9</para>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD
User's Reference Manual</emphasis>. O'Reilly &amp; Associates,
Inc., 1994.<!-- <br> --> ISBN 1-56592-075-9</para>
</listitem>
<listitem>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD User's Supplementary Documents</emphasis>.
O'Reilly &amp; Associates, Inc., 1994.<!-- <br> --> ISBN
1-56592-076-7</para>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD
User's Supplementary Documents</emphasis>. O'Reilly &amp;
Associates, Inc., 1994.<!-- <br> --> ISBN 1-56592-076-7</para>
</listitem>
<listitem>
<para><emphasis>UNIX in a Nutshell</emphasis>. O'Reilly
&amp; Associates, Inc., 1990.<!-- <br> --> ISBN
093717520X</para>
<para><emphasis>UNIX in a Nutshell</emphasis>. O'Reilly &amp;
Associates, Inc., 1990.<!-- <br> --> ISBN 093717520X</para>
</listitem>
<listitem>
<para>Mui, Linda. <emphasis>What You Need To Know When You Can't
Find Your UNIX System Administrator</emphasis>. O'Reilly
&amp; Associates, Inc., 1995. <!-- <br> --> ISBN 1-56592-104-6</para>
<para>Mui, Linda. <emphasis>What You Need To Know When You Can't Find
Your UNIX System Administrator</emphasis>. O'Reilly &amp;
Associates, Inc., 1995. <!-- <br> --> ISBN 1-56592-104-6</para>
</listitem>
<listitem>
<para><ulink URL="http://www-wks.acs.ohio-state.edu/">Ohio State
University</ulink> has written a <ulink
URL="http://www-wks.acs.ohio-state.edu/unix_course/unix.html">UNIX Introductory Course</ulink> which is available online in HTML and postscript format.</para>
URL="http://www-wks.acs.ohio-state.edu/unix_course/unix.html">UNIX
Introductory Course</ulink> which is available online in HTML and
postscript format.</para>
</listitem>
<listitem>
<para><ulink url="http://www.jp.FreeBSD.ORG/">Jpman Project,
Japan FreeBSD Users Group</ulink>. <ulink
url="http://www.pc.mycom.co.jp/FreeBSD/urm.html">FreeBSD
User's Reference Manual</ulink> (Japanese translation).
<ulink url="http://www.pc.mycom.co.jp/">Mainichi
Communications Inc.</ulink>, 1998. ISBN4-8399-0088-4
P3800E.</para>
<para><ulink url="http://www.jp.FreeBSD.ORG/">Jpman Project, Japan
FreeBSD Users Group</ulink>. <ulink
url="http://www.pc.mycom.co.jp/FreeBSD/urm.html">FreeBSD User's
Reference Manual</ulink> (Japanese translation). <ulink
url="http://www.pc.mycom.co.jp/">Mainichi Communications
Inc.</ulink>, 1998. ISBN4-8399-0088-4 P3800E.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>Administrators' Guides</title>
<itemizedlist>
<listitem>
<para>Albitz, Paul and Liu, Cricket. <emphasis>DNS and
BIND</emphasis>, 2nd Ed. O'Reilly &amp; Associates, Inc.,
1997. <!-- <br> --> ISBN 1-56592-236-0</para>
BIND</emphasis>, 2nd Ed. O'Reilly &amp; Associates, Inc., 1997.
<!-- <br> --> ISBN 1-56592-236-0</para>
</listitem>
<listitem>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD System Manager's Manual</emphasis>. O'Reilly
&amp; Associates, Inc., 1994. <!-- <br> --> ISBN
1-56592-080-5</para>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD
System Manager's Manual</emphasis>. O'Reilly &amp; Associates,
Inc., 1994. <!-- <br> --> ISBN 1-56592-080-5</para>
</listitem>
<listitem>
<para>Costales, Brian, et al. <emphasis>Sendmail</emphasis>, 2nd
Ed. O'Reilly &amp; Associates, Inc., 1997.<!-- <br> --> ISBN
<para>Costales, Brian, et al. <emphasis>Sendmail</emphasis>, 2nd Ed.
O'Reilly &amp; Associates, Inc., 1997.<!-- <br> --> ISBN
1-56592-222-0</para>
</listitem>
<listitem>
<para>Frisch, &AElig;leen. <emphasis>Essential System
Administration</emphasis>, 2nd Ed. O'Reilly &amp;
Associates, Inc., 1995. <!-- <br> -->ISBN 1-56592-127-5</para>
Administration</emphasis>, 2nd Ed. O'Reilly &amp; Associates,
Inc., 1995. <!-- <br> -->ISBN 1-56592-127-5</para>
</listitem>
<listitem>
<para>Hunt, Craig. <emphasis>TCP/IP Network
Administration</emphasis>. O'Reilly &amp; Associates, Inc.,
1992. <!-- <br> --> ISBN 0-937175-82-X</para>
Administration</emphasis>. O'Reilly &amp; Associates, Inc., 1992.
<!-- <br> --> ISBN 0-937175-82-X</para>
</listitem>
<listitem>
<para>Nemeth, Evi. <emphasis>UNIX System Administration
Handbook</emphasis>. 2nd Ed. Prentice Hall, 1995. <!-- <br>
--> ISBN 0131510517</para>
Handbook</emphasis>. 2nd Ed. Prentice Hall, 1995. <!-- <br> -->
ISBN 0131510517</para>
</listitem>
<listitem>
<para>Stern, Hal <emphasis>Managing NFS and NIS</emphasis>
O'Reilly &amp; Associates, Inc., 1991. <!-- <br> --> ISBN
<para>Stern, Hal <emphasis>Managing NFS and NIS</emphasis> O'Reilly
&amp; Associates, Inc., 1991. <!-- <br> --> ISBN
0-937175-75-7</para>
</listitem>
<listitem>
<para><ulink url="http://www.jp.FreeBSD.ORG/">Jpman Project,
Japan FreeBSD Users Group</ulink>. <ulink
url="http://www.pc.mycom.co.jp/FreeBSD/sam.html">FreeBSD
System Administrator's Manual</ulink> (Japanese translation).
<ulink url="http://www.pc.mycom.co.jp/">Mainichi
Communications Inc.</ulink>, 1998. ISBN4-8399-0109-0
P3300E.</para>
<para><ulink url="http://www.jp.FreeBSD.ORG/">Jpman Project, Japan
FreeBSD Users Group</ulink>. <ulink
url="http://www.pc.mycom.co.jp/FreeBSD/sam.html">FreeBSD System
Administrator's Manual</ulink> (Japanese translation). <ulink
url="http://www.pc.mycom.co.jp/">Mainichi Communications
Inc.</ulink>, 1998. ISBN4-8399-0109-0 P3300E.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>Programmers' Guides</title>
<itemizedlist>
<listitem>
<para>Asente, Paul. <emphasis>X Window System
Toolkit</emphasis>. Digital Press. <!-- <br> --> ISBN
1-55558-051-3</para>
<para>Asente, Paul. <emphasis>X Window System Toolkit</emphasis>.
Digital Press. <!-- <br> --> ISBN 1-55558-051-3</para>
</listitem>
<listitem>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD Programmer's Reference Manual</emphasis>.
O'Reilly &amp; Associates, Inc., 1994. <!-- <br> --> ISBN
1-56592-078-3</para>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD
Programmer's Reference Manual</emphasis>. O'Reilly &amp;
Associates, Inc., 1994. <!-- <br> --> ISBN 1-56592-078-3</para>
</listitem>
<listitem>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD Programmer's Supplementary
Documents</emphasis>. O'Reilly &amp; Associates, Inc., 1994.
<!-- <br> --> ISBN 1-56592-079-1</para>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD
Programmer's Supplementary Documents</emphasis>. O'Reilly &amp;
Associates, Inc., 1994. <!-- <br> --> ISBN 1-56592-079-1</para>
</listitem>
<listitem>
<para>Harbison, Samuel P. and Steele, Guy L. Jr. <emphasis>C: A
Reference Manual</emphasis>. 4rd ed. Prentice Hall, 1995.
<!-- <br> -->ISBN 0-13-326224-3</para>
Reference Manual</emphasis>. 4rd ed. Prentice Hall, 1995. <!--
<br> -->ISBN 0-13-326224-3</para>
</listitem>
<listitem>
<para>Kernighan, Brian and Dennis M. Ritchie. <emphasis>The C
Programming Language.</emphasis>. PTR Prentice Hall, 1988.
<!-- <br> --> ISBN 0-13-110362-9</para>
Programming Language.</emphasis>. PTR Prentice Hall, 1988. <!--
<br> --> ISBN 0-13-110362-9</para>
</listitem>
<listitem>
@ -238,15 +212,14 @@
</listitem>
<listitem>
<para>Plauger, P. J. <emphasis>The Standard C
Library</emphasis>. Prentice Hall, 1992. <!-- <br> --> ISBN
0-13-131509-9</para>
<para>Plauger, P. J. <emphasis>The Standard C Library</emphasis>.
Prentice Hall, 1992. <!-- <br> --> ISBN 0-13-131509-9</para>
</listitem>
<listitem>
<para>Stevens, W. Richard. <emphasis>Advanced Programming in the
UNIX Environment</emphasis>. Reading, Mass. :
Addison-Wesley, 1992<!-- <br> --> ISBN 0-201-56317-7</para>
<para>Stevens, W. Richard. <emphasis>Advanced Programming in the UNIX
Environment</emphasis>. Reading, Mass. : Addison-Wesley, 1992<!--
<br> --> ISBN 0-201-56317-7</para>
</listitem>
<listitem>
@ -257,72 +230,66 @@
<listitem>
<para>Wells, Bill. &ldquo;Writing Serial Drivers for UNIX&rdquo;.
<emphasis>Dr. Dobb's Journal</emphasis>. 19(15), December
1994. pp68-71, 97-99.</para>
<emphasis>Dr. Dobb's Journal</emphasis>. 19(15), December 1994.
pp68-71, 97-99.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>Operating System Internals</title>
<itemizedlist>
<listitem>
<para>Andleigh, Prabhat K. <emphasis>UNIX System
Architecture</emphasis>. Prentice-Hall, Inc., 1990.<!-- <br>
--> ISBN 0-13-949843-5</para>
Architecture</emphasis>. Prentice-Hall, Inc., 1990.<!-- <br> -->
ISBN 0-13-949843-5</para>
</listitem>
<listitem>
<para>Jolitz, William. &ldquo;Porting UNIX to the
386&rdquo;. <emphasis>Dr.
Dobb's Journal</emphasis>. January 1991-July 1992.</para>
<para>Jolitz, William. &ldquo;Porting UNIX to the 386&rdquo;.
<emphasis>Dr. Dobb's Journal</emphasis>. January 1991-July
1992.</para>
</listitem>
<listitem>
<para>Leffler, Samuel J., Marshall Kirk McKusick, Michael J
Karels and John Quarterman <emphasis>The Design and
Implementation of the 4.3BSD UNIX Operating
System</emphasis>. Reading, Mass. : Addison-Wesley,
1989.<!-- <br> --> ISBN 0-201-06196-1</para>
<para>Leffler, Samuel J., Marshall Kirk McKusick, Michael J Karels and
John Quarterman <emphasis>The Design and Implementation of the
4.3BSD UNIX Operating System</emphasis>. Reading, Mass. :
Addison-Wesley, 1989.<!-- <br> --> ISBN 0-201-06196-1</para>
</listitem>
<listitem>
<para>Leffler, Samuel J., Marshall Kirk McKusick, <emphasis>The
Design and Implementation of the 4.3BSD UNIX Operating
System: Answer Book</emphasis>. Reading, Mass. :
Addison-Wesley, 1991.<!-- <br> --> ISBN 0-201-54629-9</para>
<para>Leffler, Samuel J., Marshall Kirk McKusick, <emphasis>The Design
and Implementation of the 4.3BSD UNIX Operating System: Answer
Book</emphasis>. Reading, Mass. : Addison-Wesley, 1991.<!-- <br>
--> ISBN 0-201-54629-9</para>
</listitem>
<listitem>
<para>McKusick, Marshall Kirk, Keith Bostic, Michael J Karels,
and John Quarterman. <emphasis>The Design and Implementation
of the 4.4BSD Operating System</emphasis>. Reading, Mass. :
<para>McKusick, Marshall Kirk, Keith Bostic, Michael J Karels, and
John Quarterman. <emphasis>The Design and Implementation of the
4.4BSD Operating System</emphasis>. Reading, Mass. :
Addison-Wesley, 1996.<!-- <br> --> ISBN 0-201-54979-4</para>
</listitem>
<listitem>
<para>Stevens, W. Richard. <emphasis>TCP/IP Illustrated, Volume
1: The Protocols</emphasis>. Reading, Mass. :
Addison-Wesley, 1996.<!-- <br> --> ISBN 0-201-63346-9</para>
<para>Stevens, W. Richard. <emphasis>TCP/IP Illustrated, Volume 1:
The Protocols</emphasis>. Reading, Mass. : Addison-Wesley,
1996.<!-- <br> --> ISBN 0-201-63346-9</para>
</listitem>
<listitem>
<para>Schimmel, Curt. <emphasis>Unix Systems for Modern
Architectures</emphasis>. Reading, Mass. : Addison-Wesley,
1994. ISBN 0-201-63338-8</para>
Architectures</emphasis>. Reading, Mass. : Addison-Wesley, 1994.
ISBN 0-201-63338-8</para>
</listitem>
<listitem>
<para>Stevens, W. Richard. <emphasis>TCP/IP Illustrated, Volume
3: TCP for Transactions, HTTP, NNTP and the UNIX Domain
Protocols</emphasis>. Reading, Mass. : Addison-Wesley,
1996.<!-- <br> --> ISBN 0-201-63495-3</para>
<para>Stevens, W. Richard. <emphasis>TCP/IP Illustrated, Volume 3:
TCP for Transactions, HTTP, NNTP and the UNIX Domain
Protocols</emphasis>. Reading, Mass. : Addison-Wesley, 1996.<!--
<br> --> ISBN 0-201-63495-3</para>
</listitem>
<listitem>
@ -333,52 +300,41 @@
<listitem>
<para>Wright, Gary R. and W. Richard Stevens. <emphasis>TCP/IP
Illustrated, Volume 2: The Implementation</emphasis>.
Reading, Mass. : Addison-Wesley, 1995.<!-- <br> --> ISBN
0-201-63354-X</para>
Illustrated, Volume 2: The Implementation</emphasis>. Reading,
Mass. : Addison-Wesley, 1995.<!-- <br> --> ISBN 0-201-63354-X</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>Security Reference</title>
<itemizedlist>
<listitem>
<para>Cheswick, William R. and Steven M. Bellovin.
<emphasis>Firewalls and Internet Security: Repelling the Wily
Hacker</emphasis>. Reading, Mass. : Addison-Wesley,
1995.<!-- <br> --> ISBN 0-201-63357-4</para>
<para>Cheswick, William R. and Steven M. Bellovin. <emphasis>Firewalls
and Internet Security: Repelling the Wily Hacker</emphasis>.
Reading, Mass. : Addison-Wesley, 1995.<!-- <br> --> ISBN
0-201-63357-4</para>
</listitem>
<listitem>
<para>Garfinkel, Simson and Gene Spafford. <emphasis>Practical
UNIX Security</emphasis>. 2nd Ed. O'Reilly &amp; Associates,
Inc., 1996. <!-- <br> --> ISBN 1-56592-148-8</para>
<para>Garfinkel, Simson and Gene Spafford. <emphasis>Practical UNIX
Security</emphasis>. 2nd Ed. O'Reilly &amp; Associates, Inc.,
1996. <!-- <br> --> ISBN 1-56592-148-8</para>
</listitem>
<listitem>
<para>Garfinkel, Simson. <emphasis>PGP Pretty Good
Privacy</emphasis> O'Reilly &amp; Associates, Inc., 1995.
<!-- <br> --> ISBN 1-56592-098-8</para>
Privacy</emphasis> O'Reilly &amp; Associates, Inc., 1995. <!--
<br> --> ISBN 1-56592-098-8</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>Hardware Reference</title>
<itemizedlist>
<listitem>
<para>Anderson, Don and Tom Shanley. <emphasis>Pentium Processor
System Architecture</emphasis>. 2nd Ed. Reading, Mass. :
@ -386,10 +342,9 @@
</listitem>
<listitem>
<para>Ferraro, Richard F. <emphasis>Programmer's Guide to the
EGA, VGA, and Super VGA Cards</emphasis>. 3rd ed. Reading,
Mass. : Addison-Wesley, 1995.<!-- <br> --> ISBN
0-201-62490-7</para>
<para>Ferraro, Richard F. <emphasis>Programmer's Guide to the EGA,
VGA, and Super VGA Cards</emphasis>. 3rd ed. Reading, Mass. :
Addison-Wesley, 1995.<!-- <br> --> ISBN 0-201-62490-7</para>
</listitem>
<listitem>
@ -400,48 +355,43 @@
</listitem>
<listitem>
<para>Shanley, Tom. <emphasis>80486 System
Architecture</emphasis>. 3rd ed. Reading, Mass. :
Addison-Wesley, 1995. <!-- <br> -->ISBN 0-201-40994-1</para>
<para>Shanley, Tom. <emphasis>80486 System Architecture</emphasis>.
3rd ed. Reading, Mass. : Addison-Wesley, 1995. <!-- <br> -->ISBN
0-201-40994-1</para>
</listitem>
<listitem>
<para>Shanley, Tom. <emphasis>ISA System
Architecture</emphasis>. 3rd ed. Reading, Mass. :
Addison-Wesley, 1995.<!-- <br> --> ISBN 0-201-40996-8</para>
<para>Shanley, Tom. <emphasis>ISA System Architecture</emphasis>.
3rd ed. Reading, Mass. : Addison-Wesley, 1995.<!-- <br> --> ISBN
0-201-40996-8</para>
</listitem>
<listitem>
<para>Shanley, Tom. <emphasis>PCI System
Architecture</emphasis>. 3rd ed. Reading, Mass. :
Addison-Wesley, 1995. <!-- <br> -->ISBN 0-201-40993-3</para>
<para>Shanley, Tom. <emphasis>PCI System Architecture</emphasis>.
3rd ed. Reading, Mass. : Addison-Wesley, 1995. <!-- <br> -->ISBN
0-201-40993-3</para>
</listitem>
<listitem>
<para>Van Gilluwe, Frank. <emphasis>The Undocumented
PC</emphasis>. Reading, Mass: Addison-Wesley Pub. Co.,
1994.<!-- <br> --> ISBN 0-201-62277-7</para>
<para>Van Gilluwe, Frank. <emphasis>The Undocumented PC</emphasis>.
Reading, Mass: Addison-Wesley Pub. Co., 1994.<!-- <br> --> ISBN
0-201-62277-7</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>UNIX History</title>
<itemizedlist>
<listitem>
<para>Lion, John <emphasis>Lion's Commentary on UNIX, 6th Ed.
With Source Code</emphasis>. ITP Media Group, 1996.<!-- <br>
--> ISBN 1573980137</para>
<para>Lion, John <emphasis>Lion's Commentary on UNIX, 6th Ed. With
Source Code</emphasis>. ITP Media Group, 1996.<!-- <br> --> ISBN
1573980137</para>
</listitem>
<listitem>
<para>Raymond, Eric s. <emphasis>The New Hacker's Dictonary, 3rd
<para>Raymond, Eric S. <emphasis>The New Hacker's Dictonary, 3rd
edition</emphasis>. MIT Press, 1996.<!-- <br> --> ISBN
0-262-68092-0<!-- <br> --> Also known as the <ulink
URL="http://www.ccil.org/jargon/jargon.html">Jargon
@ -449,32 +399,32 @@
</listitem>
<listitem>
<para>Salus, Peter H. <emphasis>A quarter century of
UNIX</emphasis>. Addison-Wesley Publishing Company, Inc.,
1994.<!-- <br> --> ISBN 0-201-54777-5</para>
<para>Salus, Peter H. <emphasis>A quarter century of UNIX</emphasis>.
Addison-Wesley Publishing Company, Inc., 1994.<!-- <br> --> ISBN
0-201-54777-5</para>
</listitem>
<listitem>
<para>Simon Garfinkel, Daniel Weise, Steven Strassmann.
<emphasis>The UNIX-HATERS Handbook</emphasis>. IDG Books
Worldwide, Inc., 1994.<!-- <br> --> ISBN 1-56884-203-1</para>
<para>Simon Garfinkel, Daniel Weise, Steven Strassmann. <emphasis>The
UNIX-HATERS Handbook</emphasis>. IDG Books Worldwide, Inc.,
1994.<!-- <br> --> ISBN 1-56884-203-1</para>
</listitem>
<listitem>
<para>Don Libes, Sandy Ressler <emphasis>Life with
UNIX</emphasis> &mdash; special edition. Prentice-Hall, Inc.,
1989.<!-- <br> --> ISBN 0-13-536657-7</para>
<para>Don Libes, Sandy Ressler <emphasis>Life with UNIX</emphasis>
&mdash; special edition. Prentice-Hall, Inc., 1989.<!-- <br> -->
ISBN 0-13-536657-7</para>
</listitem>
<listitem>
<para><emphasis>The BSD family tree</emphasis>. 1997.<!-- <br>
--> <ulink
url="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/misc/bsd-family-tree">ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/misc/bsd-family-tree</ulink> or <ulink URL="file:/usr/share/misc/bsd-family-tree">local</ulink> on a FreeBSD-current machine.</para>
<para><emphasis>The BSD family tree</emphasis>. 1997.<!-- <br> -->
<ulink
url="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/misc/bsd-family-tree">ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/misc/bsd-family-tree</ulink> or <ulink URL="file:/usr/share/misc/bsd-family-tree">local</ulink> on a FreeBSD-current machine.</para>
</listitem>
<listitem>
<para><emphasis>The BSD Release Announcements
collection</emphasis>. 1997.<!-- <br> --> <ulink
<para><emphasis>The BSD Release Announcements collection</emphasis>.
1997.<!-- <br> --> <ulink
URL="http://www.de.FreeBSD.ORG/de/ftp/releases/">http://www.de.FreeBSD.ORG/de/ftp/releases/</ulink></para>
</listitem>
@ -487,19 +437,18 @@ url="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/misc/bsd-family
<listitem>
<para><emphasis>Old BSD releases from the Computer Systems Research
group (CSRG)</emphasis>. <ulink
url="http://www.mckusick.com/csrg/">http://www.mckusick.com/csrg/</ulink>: The 4CD set covers all BSD versions from 1BSD to 4.4BSD and 4.4BSD-Lite2 (but not 2.11BSD, unfortunately). As well, the last disk holds the final sources plus the SCCS files.</para>
url="http://www.mckusick.com/csrg/">http://www.mckusick.com/csrg/</ulink>:
The 4CD set covers all BSD versions from 1BSD to 4.4BSD and
4.4BSD-Lite2 (but not 2.11BSD, unfortunately). As well, the last
disk holds the final sources plus the SCCS files.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>Magazines and Journals</title>
<itemizedlist>
<listitem>
<para><emphasis>The C/C++ Users Journal</emphasis>. R&amp;D
Publications Inc. ISSN 1075-2838</para>
@ -510,13 +459,9 @@ url="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/misc/bsd-family
Administrators</emphasis> Miller Freeman, Inc., ISSN
1061-2688</para>
</listitem>
</itemizedlist>
</sect1>
</chapter>
</chapter>
<!--
Local Variables:

16
en_US.ISO_8859-1/books/handbook/book.sgml
View file

@ -36,19 +36,21 @@
<abstract>
<para>Welcome to FreeBSD! This handbook covers the installation and day
to day use of <emphasis>FreeBSD Release &rel.current;</emphasis>. This
manual is a <emphasis>work in progress</emphasis> and is the work of
many individuals. Many sections do not yet exist and some of those
to day use of <emphasis>FreeBSD Release &rel.current;</emphasis>.
This manual is a <emphasis>work in progress</emphasis> and is the work
of many individuals. Many sections do not yet exist and some of those
that do exist need to be updated. If you are interested in helping
with this project, send email to the &a.doc;. The latest version of
this document is always available from the <ulink
URL="http://www.FreeBSD.ORG/">FreeBSD World Wide Web server</ulink>.
It may also be downloaded in <ulink url="handbook.latin1">plain
text</ulink>, <ulink url="handbook.ps">postscript</ulink> or <ulink
url="handbook-html.tar.gz">HTML</ulink> with HTTP or gzip'd from the <ulink
url="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/doc/">FreeBSD FTP server</ulink> or one of the numerous <link
text</ulink>, <ulink url="handbook.ps">postscript</ulink> or <ulink
url="handbook-html.tar.gz">HTML</ulink> with HTTP or gzip'd from the
<ulink url="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/doc/">FreeBSD FTP
server</ulink> or one of the numerous <link
linkend="mirrors-ftp">mirror sites</link>. You may also want to
<ulink URL="http://www.FreeBSD.ORG/search.html">Search the Handbook</ulink>.</para>
<ulink URL="http://www.FreeBSD.ORG/search.html">Search the
Handbook</ulink>.</para>
</abstract>
</bookinfo>

6188
en_US.ISO_8859-1/books/handbook/contrib/chapter.sgml
View file

File diff suppressed because it is too large Load diff

1916
en_US.ISO_8859-1/books/handbook/cutting-edge/chapter.sgml
View file

File diff suppressed because it is too large Load diff

27
en_US.ISO_8859-1/books/handbook/disks/chapter.sgml
View file

@ -11,8 +11,8 @@
<para>Login as user <username>root</username>. After you've installed the
drive, inspect <filename>/var/run/dmesg.boot</filename> to ensure the new
disk was found. Continuing with our example, the newly added drive will be
<filename>sd1</filename> and we want to mount it on
disk was found. Continuing with our example, the newly added drive will
be <filename>sd1</filename> and we want to mount it on
<filename>/1</filename>. (if you are adding an IDE drive substitute
<filename>wd</filename> for <filename>sd</filename>)</para>
@ -37,7 +37,7 @@
<sect1>
<title>Using sysinstall</title>
<para> You may use <command>/stand/sysinstall</command> to partition and
<para>You may use <command>/stand/sysinstall</command> to partition and
label a new disk using its easy to use menus. Either login as user
<username>root</username> or use the <command>su</command> command. Run
<command>/stand/sysinstall</command> and enter the
@ -56,19 +56,20 @@
<literal>YES</literal>. Write the changes to the disk using
<command>W</command>. Now exit the FDISK editor using
<command>q</command>. Next you will be asked about the Master Boot
Record. Since you are adding a disk to an already running system, choose
<literal>None</literal>.</para>
Record. Since you are adding a disk to an already running system,
choose <literal>None</literal>.</para>
<para>Next enter the <literal>Disk Label Editor</literal>. This is where
you will create the traditional BSD partitions. A disk can have up to
eight partitions, labeled a-h. A few of the partition labels have
special uses. The <literal>a</literal> partition is used for the root
partition (<filename>/</filename>). Thus only your system disk (e.g, the
disk you boot from) should have an <literal>a</literal> partition. The
<literal>b</literal> partition is used for swap partitions, and you may
have many disks with swap partitions. The <literal>c</literal> partition
addresses the entire disk in dedicated mode, or the entire FreeBSD slice
in slice mode. The other partitions are for general use.</para>
partition (<filename>/</filename>). Thus only your system disk (e.g,
the disk you boot from) should have an <literal>a</literal> partition.
The <literal>b</literal> partition is used for swap partitions, and you
may have many disks with swap partitions. The <literal>c</literal>
partition addresses the entire disk in dedicated mode, or the entire
FreeBSD slice in slice mode. The other partitions are for general
use.</para>
<para>Sysinstall's Label editor favors the <literal>e</literal> partition
for non-root, non-swap partitions. With in the Label editor, create a
@ -107,7 +108,6 @@
&ldquo;appropriate&rdquo; any partition it finds which it doesn't
understand.</para>
<screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/rsd1 bs=1k count=1</userinput>
&prompt.root; <userinput>disklabel -Brw sd1 auto</userinput>
&prompt.root; <userinput>disklabel -e sd</userinput>1 # create the `e' partition
@ -116,17 +116,14 @@
&prompt.root; <userinput>vi /etc/fstab</userinput> # add an entry for /dev/sd1e
&prompt.root; <userinput>mount /1</userinput></screen>
<para>An alternate method is:</para>
<screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/rsd1 count=2</userinput>
&prompt.root; <userinput>disklabel /dev/rsd1 | disklabel -BrR sd1 /dev/stdin</userinput>
&prompt.root; <userinput>newfs /dev/rsd1e</userinput>
&prompt.root; <userinput>mkdir -p /1</userinput>
&prompt.root; <userinput>vi /etc/fstab</userinput> # add an entry for /dev/sd1e
&prompt.root; <userinput>mount /1</userinput></screen>
</sect2>
</sect1>

672
en_US.ISO_8859-1/books/handbook/eresources/chapter.sgml
View file

File diff suppressed because it is too large Load diff

4585
en_US.ISO_8859-1/books/handbook/hw/chapter.sgml
View file

File diff suppressed because it is too large Load diff

886
en_US.ISO_8859-1/books/handbook/install/chapter.sgml
View file

File diff suppressed because it is too large Load diff

1108
en_US.ISO_8859-1/books/handbook/internals/chapter.sgml
View file

File diff suppressed because it is too large Load diff

760
en_US.ISO_8859-1/books/handbook/introduction/chapter.sgml
View file

@ -1,170 +1,156 @@
<chapter id="introduction">
<chapter id="introduction">
<title>Introduction</title>
<para>FreeBSD is a 4.4BSD-Lite based operating system for Intel
architecture (x86) based PCs. For an overview of FreeBSD, see
<link linkend="nutshell">FreeBSD in a nutshell</link>. For a
history of the project, read <link linkend="history">a brief
history of FreeBSD</link>. To see a description of the latest release,
read <link linkend="relnotes">about the current
release</link>. If you're interested in contributing something to the
FreeBSD project (code, equipment, sacks of unmarked bills), please see
about <link linkend="contrib">contributing to FreeBSD</link>.</para>
<para>FreeBSD is a 4.4BSD-Lite based operating system for Intel architecture
(x86) based PCs. For an overview of FreeBSD, see <link
linkend="nutshell">FreeBSD in a nutshell</link>. For a history of the
project, read <link linkend="history">a brief history of FreeBSD</link>.
To see a description of the latest release, read <link
linkend="relnotes">about the current release</link>. If you're
interested in contributing something to the FreeBSD project (code,
equipment, sacks of unmarked bills), please see about <link
linkend="contrib">contributing to FreeBSD</link>.</para>
<sect1 id="nutshell">
<title>FreeBSD in a Nutshell</title>
<para>FreeBSD is a state of the art operating system for personal
computers based on the Intel CPU architecture, which includes the
386, 486 and Pentium processors (both SX and DX versions). Intel
compatible CPUs from AMD and Cyrix are supported as well. FreeBSD
provides you with many advanced features previously available only
on much more expensive computers. These features include:</para>
computers based on the Intel CPU architecture, which includes the 386,
486 and Pentium processors (both SX and DX versions). Intel compatible
CPUs from AMD and Cyrix are supported as well. FreeBSD provides you
with many advanced features previously available only on much more
expensive computers. These features include:</para>
<itemizedlist>
<listitem>
<para><emphasis>Preemptive multitasking</emphasis> with
dynamic priority adjustment to ensure smooth and fair sharing
of the computer between applications and users.</para>
<para><emphasis>Preemptive multitasking</emphasis> with dynamic
priority adjustment to ensure smooth and fair sharing of the
computer between applications and users.</para>
</listitem>
<listitem>
<para><emphasis>Multiuser</emphasis> access means that
many people can use a FreeBSD system simultaneously for a
variety of things. System peripherals such as printers and
tape drives are also properly SHARED BETWEEN ALL users on the
system.</para>
<para><emphasis>Multiuser</emphasis> access means that many people can
use a FreeBSD system simultaneously for a variety of things. System
peripherals such as printers and tape drives are also properly
SHARED BETWEEN ALL users on the system.</para>
</listitem>
<listitem>
<para>Complete <emphasis>TCP/IP networking</emphasis>
including SLIP, PPP, NFS and NIS support. This means that
your FreeBSD machine can inter-operate easily with other
systems as well act as an enterprise server, providing vital
functions such as NFS (remote file access) and e-mail services
or putting your organization on the Internet with WWW, ftp,
routing and firewall (security) services.</para>
<para>Complete <emphasis>TCP/IP networking</emphasis> including SLIP,
PPP, NFS and NIS support. This means that your FreeBSD machine can
inter-operate easily with other systems as well act as an enterprise
server, providing vital functions such as NFS (remote file access)
and e-mail services or putting your organization on the Internet
with WWW, ftp, routing and firewall (security) services.</para>
</listitem>
<listitem>
<para><emphasis>Memory protection</emphasis> ensures
that applications (or users) cannot interfere with each other.
One application crashing will not affect others in any
way.</para>
<para><emphasis>Memory protection</emphasis> ensures that applications
(or users) cannot interfere with each other. One application
crashing will not affect others in any way.</para>
</listitem>
<listitem>
<para>FreeBSD is a <emphasis>32-bit</emphasis>
operating system and was designed as such from the ground
up.</para>
<para>FreeBSD is a <emphasis>32-bit</emphasis> operating system and
was designed as such from the ground up.</para>
</listitem>
<listitem>
<para>The industry standard <emphasis>X Window
System</emphasis> (X11R6) provides a graphical user
interface (GUI) for the cost of a common VGA card and monitor
and comes with full sources.</para>
<para>The industry standard <emphasis>X Window System</emphasis>
(X11R6) provides a graphical user interface (GUI) for the cost of a
common VGA card and monitor and comes with full sources.</para>
</listitem>
<listitem>
<para><emphasis>Binary compatibility</emphasis> with
many programs built for SCO, BSDI, NetBSD, Linux and
386BSD.</para>
<para><emphasis>Binary compatibility</emphasis> with many programs
built for SCO, BSDI, NetBSD, Linux and 386BSD.</para>
</listitem>
<listitem>
<para>Hundreds of <emphasis>ready-to-run</emphasis>
applications are available from the FreeBSD <emphasis>ports</emphasis> and <emphasis>packages</emphasis> collection. Why search the net
when you can find it all right here?</para>
<para>Hundreds of <emphasis>ready-to-run</emphasis> applications are
available from the FreeBSD <emphasis>ports</emphasis> and
<emphasis>packages</emphasis> collection. Why search the net when
you can find it all right here?</para>
</listitem>
<listitem>
<para>Thousands of additional and <emphasis>easy-to-port</emphasis> applications available on
the Internet. FreeBSD is source code compatible with most
popular commercial Unix systems and thus most applications
require few, if any, changes to compile.</para>
<para>Thousands of additional and <emphasis>easy-to-port</emphasis>
applications available on the Internet. FreeBSD is source code
compatible with most popular commercial Unix systems and thus most
applications require few, if any, changes to compile.</para>
</listitem>
<listitem>
<para>Demand paged <emphasis>virtual memory</emphasis>
and &ldquo;merged VM/buffer cache&rdquo; design efficiently satisfies
applications with large appetites for memory while still
maintaining interactive response to other users.</para>
<para>Demand paged <emphasis>virtual memory</emphasis> and
&ldquo;merged VM/buffer cache&rdquo; design efficiently satisfies
applications with large appetites for memory while still maintaining
interactive response to other users.</para>
</listitem>
<listitem>
<para><emphasis>Shared libraries</emphasis> (the Unix
equivalent of MS-Windows DLLs) provide for efficient use of
disk space and memory.</para>
<para><emphasis>Shared libraries</emphasis> (the Unix equivalent of
MS-Windows DLLs) provide for efficient use of disk space and
memory.</para>
</listitem>
<listitem>
<para>A full complement of <emphasis>C</emphasis>,
<emphasis>C++</emphasis> and <emphasis>Fortran</emphasis> development tools. Many
additional languages for advanced research and development are
also available in the ports and packages collection.</para>
<emphasis>C++</emphasis> and <emphasis>Fortran</emphasis>
development tools. Many additional languages for advanced research
and development are also available in the ports and packages
collection.</para>
</listitem>
<listitem>
<para><emphasis>Source code</emphasis> for the entire
system means you have the greatest degree of control over your
environment. Why be locked into a proprietary solution and at
the mercy of your vendor when you can have a truly Open
System?</para>
<para><emphasis>Source code</emphasis> for the entire system means you
have the greatest degree of control over your environment. Why be
locked into a proprietary solution and at the mercy of your vendor
when you can have a truly Open System?</para>
</listitem>
<listitem>
<para>Extensive <emphasis>on-line
documentation</emphasis>.</para>
<para>Extensive <emphasis>on-line documentation</emphasis>.</para>
</listitem>
<listitem>
<para><emphasis>And many more!</emphasis></para>
</listitem>
</itemizedlist>
<para>FreeBSD is based on the 4.4BSD-Lite release from Computer Systems
Research Group (CSRG) at the University of California at Berkeley, and
carries on the distinguished tradition of BSD systems development. In
addition to the fine work provided by CSRG, the FreeBSD Project has put
in many thousands of hours in fine tuning the system for maximum
performance and reliability in real-life load situations. As many of
the commercial giants struggle to field PC operating systems with such
features, performance and reliability, FreeBSD can offer them
<emphasis>now</emphasis>!</para>
<para>FreeBSD is based on the 4.4BSD-Lite release from Computer
Systems Research Group (CSRG) at the University of California at
Berkeley, and carries on the distinguished tradition of BSD systems
development. In addition to the fine work provided by CSRG, the
FreeBSD Project has put in many thousands of hours in fine tuning
the system for maximum performance and reliability in real-life load
situations. As many of the commercial giants struggle to field PC
operating systems with such features, performance and reliability,
FreeBSD can offer them <emphasis>now</emphasis>!</para>
<para>The applications to which FreeBSD can be put are truly limited
only by your own imagination. From software development to factory
automation, inventory control to azimuth correction of remote
satellite antennae; if it can be done with a commercial UNIX product
then it is more than likely that you can do it with FreeBSD, too!
FreeBSD also benefits significantly from the literally thousands of
high quality applications developed by research centers and
universities around the world, often available at little to no cost.
Commercial applications are also available and appearing in greater
numbers every day.</para>
<para>Because the source code for FreeBSD itself is generally
available, the system can also be customized to an almost unheard of
degree for special applications or projects, and in ways not
generally possible with operating systems from most major commercial
vendors. Here is just a sampling of some of the applications in
which people are currently using FreeBSD:</para>
<para>The applications to which FreeBSD can be put are truly limited only
by your own imagination. From software development to factory
automation, inventory control to azimuth correction of remote satellite
antennae; if it can be done with a commercial UNIX product then it is
more than likely that you can do it with FreeBSD, too! FreeBSD also
benefits significantly from the literally thousands of high quality
applications developed by research centers and universities around the
world, often available at little to no cost. Commercial applications are
also available and appearing in greater numbers every day.</para>
<para>Because the source code for FreeBSD itself is generally available,
the system can also be customized to an almost unheard of degree for
special applications or projects, and in ways not generally possible
with operating systems from most major commercial vendors. Here is just
a sampling of some of the applications in which people are currently
using FreeBSD:</para>
<itemizedlist>
<listitem>
<para><emphasis>Internet Services:</emphasis> The
robust TCP/IP networking built into FreeBSD makes it an ideal
platform for a variety of Internet services such as:</para>
<itemizedlist>
<para><emphasis>Internet Services:</emphasis> The robust TCP/IP
networking built into FreeBSD makes it an ideal platform for a
variety of Internet services such as:</para>
<itemizedlist>
<listitem>
<para>FTP servers</para>
</listitem>
@ -192,71 +178,62 @@
<listitem>
<para>And more...</para>
</listitem>
</itemizedlist>
<para>You can easily start out small with an
inexpensive 386 class PC and upgrade as your enterprise
grows.</para>
<para>You can easily start out small with an inexpensive 386 class PC
and upgrade as your enterprise grows.</para>
</listitem>
<listitem>
<para><emphasis>Education:</emphasis> Are you a student
of computer science or a related engineering field? There is
no better way of learning about operating systems, computer
architecture and networking than the hands on, under the hood
experience that FreeBSD can provide. A number of freely
available CAD, mathematical and graphic design packages also
make it highly useful to those whose primary interest in a
computer is to get <emphasis>other</emphasis> work
done!</para>
<para><emphasis>Education:</emphasis> Are you a student of computer
science or a related engineering field? There is no better way of
learning about operating systems, computer architecture and
networking than the hands on, under the hood experience that FreeBSD
can provide. A number of freely available CAD, mathematical and
graphic design packages also make it highly useful to those whose
primary interest in a computer is to get <emphasis>other</emphasis>
work done!</para>
</listitem>
<listitem>
<para><emphasis>Research:</emphasis> With source code
for the entire system available, FreeBSD is an excellent
platform for research in operating systems as well as other
branches of computer science. FreeBSD's freely available
nature also makes it possible for remote groups to collaborate
on ideas or shared development without having to worry about
special licensing agreements or limitations on what may be
discussed in open forums.</para>
<para><emphasis>Research:</emphasis> With source code for the entire
system available, FreeBSD is an excellent platform for research in
operating systems as well as other branches of computer science.
FreeBSD's freely available nature also makes it possible for remote
groups to collaborate on ideas or shared development without having
to worry about special licensing agreements or limitations on what
may be discussed in open forums.</para>
</listitem>
<listitem>
<para><emphasis>Networking:</emphasis> Need a new
router? A name server (DNS)? A firewall to keep people out
of your internal network? FreeBSD can easily turn that unused
386 or 486 PC sitting in the corner into an advanced router
with sophisticated packet filtering capabilities.</para>
<para><emphasis>Networking:</emphasis> Need a new router? A name
server (DNS)? A firewall to keep people out of your internal
network? FreeBSD can easily turn that unused 386 or 486 PC sitting
in the corner into an advanced router with sophisticated packet
filtering capabilities.</para>
</listitem>
<listitem>
<para><emphasis>X Window workstation:</emphasis>
FreeBSD is a fine choice for an inexpensive X terminal
solution, either using the freely available XFree86 server or
one of the excellent commercial servers provided by X Inside.
Unlike an X terminal, FreeBSD allows many applications to be
run locally, if desired, thus relieving the burden on a
central server. FreeBSD can even boot &ldquo;diskless&rdquo;, making
individual workstations even cheaper and easier to
administer.</para>
<para><emphasis>X Window workstation:</emphasis> FreeBSD is a fine
choice for an inexpensive X terminal solution, either using the
freely available XFree86 server or one of the excellent commercial
servers provided by X Inside. Unlike an X terminal, FreeBSD allows
many applications to be run locally, if desired, thus relieving the
burden on a central server. FreeBSD can even boot
&ldquo;diskless&rdquo;, making individual workstations even cheaper
and easier to administer.</para>
</listitem>
<listitem>
<para><emphasis>Software Development:</emphasis> The
basic FreeBSD system comes with a full complement of
development tools including the renowned GNU C/C++ compiler
and debugger.</para>
<para><emphasis>Software Development:</emphasis> The basic FreeBSD
system comes with a full complement of development tools including
the renowned GNU C/C++ compiler and debugger.</para>
</listitem>
</itemizedlist>
<para>FreeBSD is available in both source and binary form on CDROM and
via anonymous ftp. See <link linkend="mirrors">Obtaining
FreeBSD</link> for more details.</para>
<para>FreeBSD is available in both source and binary form on CDROM and via
anonymous ftp. See <link linkend="mirrors">Obtaining FreeBSD</link>
for more details.</para>
</sect1>
<sect1 id="history">
@ -265,101 +242,96 @@
<para><emphasis>Contributed by &a.jkh;</emphasis>.</para>
<para>The FreeBSD project had its genesis in the early part of 1993,
partially as an outgrowth of the &ldquo;Unofficial 386BSD Patchkit&rdquo; by the
patchkit's last 3 coordinators: Nate Williams, Rod Grimes and
myself.</para>
partially as an outgrowth of the &ldquo;Unofficial 386BSD
Patchkit&rdquo; by the patchkit's last 3 coordinators: Nate Williams,
Rod Grimes and myself.</para>
<para>Our original goal was to produce an intermediate snapshot of
386BSD in order to fix a number of problems with it that the
patchkit mechanism just was not capable of solving. Some of you may
remember the early working title for the project being &ldquo;386BSD 0.5&rdquo;
or &ldquo;386BSD Interim&rdquo; in reference to that fact.</para>
<para>Our original goal was to produce an intermediate snapshot of 386BSD
in order to fix a number of problems with it that the patchkit mechanism
just was not capable of solving. Some of you may remember the early
working title for the project being &ldquo;386BSD 0.5&rdquo; or
&ldquo;386BSD Interim&rdquo; in reference to that fact.</para>
<para>386BSD was Bill Jolitz's operating system, which had been up to
that point suffering rather severely from almost a year's worth of
neglect. As the patchkit swelled ever more uncomfortably with each
passing day, we were in unanimous agreement that something had to be
done and decided to try and assist Bill by providing this interim
&ldquo;cleanup&rdquo; snapshot. Those plans came to a rude halt when Bill
Jolitz suddenly decided to withdraw his sanction from the project
and without any clear indication of what would be done
instead.</para>
<para>386BSD was Bill Jolitz's operating system, which had been up to that
point suffering rather severely from almost a year's worth of neglect.
As the patchkit swelled ever more uncomfortably with each passing day,
we were in unanimous agreement that something had to be done and decided
to try and assist Bill by providing this interim &ldquo;cleanup&rdquo;
snapshot. Those plans came to a rude halt when Bill Jolitz suddenly
decided to withdraw his sanction from the project and without any clear
indication of what would be done instead.</para>
<para>It did not take us long to decide that the goal remained
worthwhile, even without Bill's support, and so we adopted the name
&ldquo;FreeBSD&rdquo;, coined by David Greenman. Our initial objectives were
set after consulting with the system's current users and, once it
became clear that the project was on the road to perhaps even
becoming a reality, I contacted Walnut Creek CDROM with an eye
towards improving FreeBSD's distribution channels for those many
unfortunates without easy access to the Internet. Walnut Creek
CDROM not only supported the idea of distributing FreeBSD on CD but
went so far as to provide the project with a machine to work on and
a fast Internet connection. Without Walnut Creek CDROM's almost
unprecedented degree of faith in what was, at the time, a completely
unknown project, it is quite unlikely that FreeBSD would have gotten
as far, as fast, as it has today.</para>
<para>It did not take us long to decide that the goal remained worthwhile,
even without Bill's support, and so we adopted the name
&ldquo;FreeBSD&rdquo;, coined by David Greenman. Our initial objectives
were set after consulting with the system's current users and, once it
became clear that the project was on the road to perhaps even becoming a
reality, I contacted Walnut Creek CDROM with an eye towards improving
FreeBSD's distribution channels for those many unfortunates without easy
access to the Internet. Walnut Creek CDROM not only supported the idea
of distributing FreeBSD on CD but went so far as to provide the project
with a machine to work on and a fast Internet connection. Without
Walnut Creek CDROM's almost unprecedented degree of faith in what was,
at the time, a completely unknown project, it is quite unlikely that
FreeBSD would have gotten as far, as fast, as it has today.</para>
<para>The first CDROM (and general net-wide) distribution was FreeBSD
1.0, released in December of 1993. This was based on the
4.3BSD-Lite (&ldquo;Net/2&rdquo;) tape from U.C. Berkeley, with many components
also provided by 386BSD and the Free Software Foundation. It was a
fairly reasonable success for a first offering, and we followed it
with the highly successful FreeBSD 1.1 release in May of
1994.</para>
<para>The first CDROM (and general net-wide) distribution was FreeBSD 1.0,
released in December of 1993. This was based on the 4.3BSD-Lite
(&ldquo;Net/2&rdquo;) tape from U.C. Berkeley, with many components also
provided by 386BSD and the Free Software Foundation. It was a fairly
reasonable success for a first offering, and we followed it with the
highly successful FreeBSD 1.1 release in May of 1994.</para>
<para>Around this time, some rather unexpected storm clouds formed on
the horizon as Novell and U.C. Berkeley settled their long-running
lawsuit over the legal status of the Berkeley Net/2 tape. A
condition of that settlement was U.C. Berkeley's concession that
large parts of Net/2 were &ldquo;encumbered&rdquo; code and the property of
Novell, who had in turn acquired it from AT&amp;T some time
previously. What Berkeley got in return was Novell's &ldquo;blessing&rdquo;
that the 4.4BSD-Lite release, when it was finally released, would be
declared unencumbered and all existing Net/2 users would be strongly
encouraged to switch. This included FreeBSD, and the project was
given until the end of July 1994 to stop shipping its own Net/2
based product. Under the terms of that agreement, the project was
allowed one last release before the deadline, that release being
FreeBSD 1.1.5.1.</para>
<para>Around this time, some rather unexpected storm clouds formed on the
horizon as Novell and U.C. Berkeley settled their long-running lawsuit
over the legal status of the Berkeley Net/2 tape. A condition of that
settlement was U.C. Berkeley's concession that large parts of Net/2 were
&ldquo;encumbered&rdquo; code and the property of Novell, who had in
turn acquired it from AT&amp;T some time previously. What Berkeley got
in return was Novell's &ldquo;blessing&rdquo; that the 4.4BSD-Lite
release, when it was finally released, would be declared unencumbered
and all existing Net/2 users would be strongly encouraged to switch.
This included FreeBSD, and the project was given until the end of July
1994 to stop shipping its own Net/2 based product. Under the terms of
that agreement, the project was allowed one last release before the
deadline, that release being FreeBSD 1.1.5.1.</para>
<para>FreeBSD then set about the arduous task of literally
re-inventing itself from a completely new and rather incomplete set
of 4.4BSD-Lite bits. The &ldquo;Lite&rdquo; releases were light in part because
Berkeley's CSRG had removed large chunks of code required for
actually constructing a bootable running system (due to various
legal requirements) and the fact that the Intel port of 4.4 was
highly incomplete. It took the project until December of 1994 to
make this transition, and in January of 1995 it released FreeBSD 2.0
to the net and on CDROM. Despite being still more than a little
rough around the edges, the release was a significant success and
was followed by the more robust and easier to install FreeBSD 2.0.5
release in June of 1995.</para>
<para>FreeBSD then set about the arduous task of literally re-inventing
itself from a completely new and rather incomplete set of 4.4BSD-Lite
bits. The &ldquo;Lite&rdquo; releases were light in part because
Berkeley's CSRG had removed large chunks of code required for actually
constructing a bootable running system (due to various legal
requirements) and the fact that the Intel port of 4.4 was highly
incomplete. It took the project until December of 1994 to make this
transition, and in January of 1995 it released FreeBSD 2.0 to the net
and on CDROM. Despite being still more than a little rough around the
edges, the release was a significant success and was followed by the
more robust and easier to install FreeBSD 2.0.5 release in June of
1995.</para>
<para>We released FreeBSD 2.1.5 in August of 1996, and it appeared to
be popular enough among the ISP and commercial communities that
another release along the 2.1-stable branch was merited. This was
FreeBSD 2.1.7.1, released in February 1997 and capping the end of
mainstream development on 2.1-stable. Now in maintenance mode, only
security enhancements and other critical bug fixes will be done on
this branch (RELENG_2_1_0).</para>
<para>We released FreeBSD 2.1.5 in August of 1996, and it appeared to be
popular enough among the ISP and commercial communities that another
release along the 2.1-stable branch was merited. This was FreeBSD
2.1.7.1, released in February 1997 and capping the end of mainstream
development on 2.1-stable. Now in maintenance mode, only security
enhancements and other critical bug fixes will be done on this branch
(RELENG_2_1_0).</para>
<para>FreeBSD 2.2 was branched from the development mainline
(&ldquo;-current&rdquo;) in November 1996 as the RELENG_2_2 branch, and the
first full release (2.2.1) was released in April, 1997. Further
releases along the 2.2 branch were done in the Summer and Fall of
'97, the latest being 2.2.7 which appeared in late July of '98.
The first official 3.0 release appeared in October, 1998 and the
last release on the 2.2 branch, 2.2.8, appeared in November,
1998.</para>
(&ldquo;-current&rdquo;) in November 1996 as the RELENG_2_2 branch, and
the first full release (2.2.1) was released in April, 1997. Further
releases along the 2.2 branch were done in the Summer and Fall of '97,
the latest being 2.2.7 which appeared in late July of '98. The first
official 3.0 release appeared in October, 1998 and the last release on
the 2.2 branch, 2.2.8, appeared in November, 1998.</para>
<para>The tree branched again on Jan 20, 1999. This led to
4.0-current and a 3.x-stable branch, from which 3.1 will be
released on February 15th, 1999.</para>
<para>The tree branched again on Jan 20, 1999. This led to 4.0-current
and a 3.x-stable branch, from which 3.1 will be released on February
15th, 1999.</para>
<para>Long term development projects will continue to take place in
the 4.0-current branch and SNAPshot releases of 4.0 on CDROM (and,
of course, on the net).</para>
<para>Long term development projects will continue to take place in the
4.0-current branch and SNAPshot releases of 4.0 on CDROM (and, of
course, on the net).</para>
</sect1>
<sect1 id="goals">
@ -367,25 +339,24 @@
<para><emphasis>Contributed by &a.jkh;</emphasis>.</para>
<para>The goals of the FreeBSD Project are to provide software that
may be used for any purpose and without strings attached. Many of
us have a significant investment in the code (and project) and would
certainly not mind a little financial compensation now and then, but
we're definitely not prepared to insist on it. We believe that our
first and foremost &ldquo;mission&rdquo; is to provide code to any and all
comers, and for whatever purpose, so that the code gets the widest
possible use and provides the widest possible benefit. This is, I
believe, one of the most fundamental goals of Free Software and one
that we enthusiastically support.</para>
<para>The goals of the FreeBSD Project are to provide software that may be
used for any purpose and without strings attached. Many of us have a
significant investment in the code (and project) and would certainly not
mind a little financial compensation now and then, but we're definitely
not prepared to insist on it. We believe that our first and foremost
&ldquo;mission&rdquo; is to provide code to any and all comers, and for
whatever purpose, so that the code gets the widest possible use and
provides the widest possible benefit. This is, I believe, one of the
most fundamental goals of Free Software and one that we enthusiastically
support.</para>
<para>That code in our source tree which falls under the GNU Public
License (GPL) or GNU Library Public License (GLPL) comes with
slightly more strings attached, though at least on the side of
enforced access rather than the usual opposite. Due to the
additional complexities that can evolve in the commercial use of GPL
software, we do, however, endeavor to replace such software with
submissions under the more relaxed BSD copyright whenever possible.</para>
License (GPL) or GNU Library Public License (GLPL) comes with slightly
more strings attached, though at least on the side of enforced access
rather than the usual opposite. Due to the additional complexities that
can evolve in the commercial use of GPL software, we do, however,
endeavor to replace such software with submissions under the more
relaxed BSD copyright whenever possible.</para>
</sect1>
<sect1 id="development">
@ -396,222 +367,225 @@
<para>The development of FreeBSD is a very open and flexible process,
FreeBSD being literally built from the contributions of hundreds of
people around the world, as can be seen from our <link
linkend="staff">list of contributors</link>. We are constantly
on the lookout for new developers and ideas, and those interested in
becoming more closely involved with the project need simply contact
us at the &a.hackers;. Those who prefer to work more independently
are also accommodated, and they are free to use our FTP facilities
at <ulink
URL="ftp://ftp.freebsd.org/pub/FreeBSD/incoming">ftp.freebsd.org</ulink> to distribute their own patches or work-in-progress sources. The &a.announce; is also available to those wishing to make other FreeBSD users aware of major areas of work.</para>
<para>Useful things to know about the FreeBSD project and its
development process, whether working independently or in close
cooperation:</para>
linkend="staff">list of contributors</link>. We are constantly on the
lookout for new developers and ideas, and those interested in becoming
more closely involved with the project need simply contact us at the
&a.hackers;. Those who prefer to work more independently are also
accommodated, and they are free to use our FTP facilities at <ulink
URL="ftp://ftp.freebsd.org/pub/FreeBSD/incoming">ftp.freebsd.org</ulink>
to distribute their own patches or work-in-progress sources. The
&a.announce; is also available to those wishing to make other FreeBSD
users aware of major areas of work.</para>
<para>Useful things to know about the FreeBSD project and its development
process, whether working independently or in close cooperation:</para>
<variablelist>
<varlistentry><term>The CVS
repository<anchor id="development-cvs-repository"></term>
<varlistentry>
<term>The CVS repository<anchor
id="development-cvs-repository"></term>
<listitem>
<para>The central source tree for FreeBSD is maintained by
<ulink
URL="http://www.cyclic.com/cyclic-pages/CVS-sheet.html">CVS</ulink> (Concurrent Version System), a freely available source code control tool which comes bundled with FreeBSD. The primary <ulink URL="http://www.freebsd.org/cgi/cvsweb.cgi">CVS repository</ulink> resides on a machine in Concord CA, USA from where it is replicated to numerous mirror machines throughout the world. The CVS tree, as well as the <link linkend="current">-current</link> and <link
linkend="stable">-stable</link> trees which are checked
out of it, can be easily replicated to your own machine as
well. Please refer to the
<link linkend="synching">Synchronizing your source
<para>The central source tree for FreeBSD is maintained by <ulink
URL="http://www.cyclic.com/cyclic-pages/CVS-sheet.html">CVS</ulink>
(Concurrent Version System), a freely available source code
control tool which comes bundled with FreeBSD. The primary <ulink
URL="http://www.freebsd.org/cgi/cvsweb.cgi">CVS
repository</ulink> resides on a machine in Concord CA, USA from
where it is replicated to numerous mirror machines throughout the
world. The CVS tree, as well as the <link
linkend="current">-current</link> and <link
linkend="stable">-stable</link> trees which are checked out of
it, can be easily replicated to your own machine as well. Please
refer to the <link linkend="synching">Synchronizing your source
tree</link> section for more information on doing this.</para>
</listitem>
</varlistentry>
<varlistentry><term>The committers
list<anchor id="development-committers"></term>
<varlistentry>
<term>The committers list<anchor id="development-committers"></term>
<listitem>
<para>The <link linkend="staff-committers">committers</link>
are the people who have <emphasis>write</emphasis> access to
the CVS tree, and are thus authorized to make modifications
to the FreeBSD source (the term &ldquo;committer&rdquo; comes from the
&man.cvs.1; <command>commit</command> command, which is used to
bring new changes into the CVS repository). The best way of
making submissions for review by the committers list is to
use the &man.send-pr.1; command, though if something appears to be jammed in the system then you may also reach them by sending mail to <email>committers@freebsd.org</email>.</para>
<para>The <link linkend="staff-committers">committers</link> are the
people who have <emphasis>write</emphasis> access to the CVS tree,
and are thus authorized to make modifications to the FreeBSD
source (the term &ldquo;committer&rdquo; comes from the
&man.cvs.1; <command>commit</command> command, which is used
to bring new changes into the CVS repository). The best way of
making submissions for review by the committers list is to use the
&man.send-pr.1; command, though if something appears to be
jammed in the system then you may also reach them by sending mail
to <email>committers@freebsd.org</email>.</para>
</listitem>
</varlistentry>
<varlistentry><term>The FreeBSD core
team<anchor id="development-core"></term>
<varlistentry>
<term>The FreeBSD core team<anchor id="development-core"></term>
<listitem>
<para>The <link linkend="staff-core">FreeBSD core
team</link> would be equivalent to the board of directors if
the FreeBSD Project were a company. The primary task of the
core team is to make sure the project, as a whole, is in
good shape and is heading in the right directions. Inviting
dedicated and responsible developers to join our group of
committers is one of the functions of the core team, as is
the recruitment of new core team members as others move on.
Most current members of the core team started as committers
who's addiction to the project got the better of
<para>The <link linkend="staff-core">FreeBSD core team</link> would
be equivalent to the board of directors if the FreeBSD Project
were a company. The primary task of the core team is to make sure
the project, as a whole, is in good shape and is heading in the
right directions. Inviting dedicated and responsible developers
to join our group of committers is one of the functions of the
core team, as is the recruitment of new core team members as
others move on. Most current members of the core team started as
committers who's addiction to the project got the better of
them.</para>
<para>Some core team members also have specific <link
linkend="staff-who">areas of responsibility</link>,
meaning that they are committed to ensuring that some large
portion of the system works as advertised.</para>
linkend="staff-who">areas of responsibility</link>, meaning that
they are committed to ensuring that some large portion of the
system works as advertised.</para>
<note>
<para>Most members of the core team are volunteers when it
comes to FreeBSD development and do not benefit from the
project financially, so &ldquo;commitment&rdquo; should also not be
<para>Most members of the core team are volunteers when it comes
to FreeBSD development and do not benefit from the project
financially, so &ldquo;commitment&rdquo; should also not be
misconstrued as meaning &ldquo;guaranteed support.&rdquo; The
&ldquo;board of directors&rdquo; analogy above is not
actually very accurate, and it may be more suitable to say
that these are the people who gave up their lives in favor
of FreeBSD against their better judgement! <!-- smiley --><emphasis>;)</emphasis></para>
&ldquo;board of directors&rdquo; analogy above is not actually
very accurate, and it may be more suitable to say that these are
the people who gave up their lives in favor of FreeBSD against
their better judgement! <!-- smiley
--><emphasis>;)</emphasis></para>
</note>
</listitem>
</varlistentry>
<varlistentry><term>Outside
contributors</term>
<varlistentry>
<term>Outside contributors</term>
<listitem>
<para>Last, but definitely not least, the largest group of
developers are the users themselves who provide feedback and
bug-fixes to us on an almost constant basis. The primary
way of keeping in touch with FreeBSD's more non-centralized
development is to subscribe to the &a.hackers; (see <link
linkend="eresources-mail">mailing list
info</link>) where such things are discussed.</para>
bug-fixes to us on an almost constant basis. The primary way of
keeping in touch with FreeBSD's more non-centralized development
is to subscribe to the &a.hackers; (see <link
linkend="eresources-mail">mailing list info</link>) where such
things are discussed.</para>
<para><link linkend="contrib-additional">The list</link> of
those who have contributed something which made its way into
our source tree is a long and growing one, so why not join
it by contributing something back to FreeBSD today?
<!-- smiley --><emphasis>:-)</emphasis></para>
<para><link linkend="contrib-additional">The list</link> of those
who have contributed something which made its way into our source
tree is a long and growing one, so why not join it by contributing
something back to FreeBSD today? <!-- smiley
--><emphasis>:-)</emphasis></para>
<para>Providing code is not the only way of contributing to
the project; for a more complete list of things that need
doing, please refer to the <link linkend="contrib">how to
<para>Providing code is not the only way of contributing to the
project; for a more complete list of things that need doing,
please refer to the <link linkend="contrib">how to
contribute</link> section in this handbook.</para>
</listitem>
</varlistentry>
</variablelist>
<para>In summary, our development model is organized as a loose set of
concentric circles. The centralized model is designed for the
convenience of the <emphasis>users</emphasis> of FreeBSD, who are
thereby provided with an easy way of tracking one central code base,
not to keep potential contributors out! Our desire is to present a
stable operating system with a large set of coherent <link
linkend="ports">application programs</link> that the users can easily install
and use, and this model works very well in accomplishing
thereby provided with an easy way of tracking one central code base, not
to keep potential contributors out! Our desire is to present a stable
operating system with a large set of coherent <link
linkend="ports">application programs</link> that the users can easily
install and use, and this model works very well in accomplishing
that.</para>
<para>All we ask of those who would join us as FreeBSD developers is
some of the same dedication its current people have to its continued
<para>All we ask of those who would join us as FreeBSD developers is some
of the same dedication its current people have to its continued
success!</para>
</sect1>
<sect1 id="relnotes">
<title>About the Current Release</title>
<para>FreeBSD is a freely available, full source 4.4BSD-Lite based
release for Intel i386/i486/Pentium/PentiumPro/Pentium II (or
compatible) based PC's. It is based primarily on software from U.C.
Berkeley's CSRG group, with some enhancements from NetBSD, OpenBSD,
386BSD, and the Free Software Foundation.</para>
<para>FreeBSD is a freely available, full source 4.4BSD-Lite based release
for Intel i386/i486/Pentium/PentiumPro/Pentium II (or compatible) based
PC's. It is based primarily on software from U.C. Berkeley's CSRG
group, with some enhancements from NetBSD, OpenBSD, 386BSD, and the Free
Software Foundation.</para>
<para>Since our release of FreeBSD 2.0 in January of 95, the
performance, feature set, and stability of FreeBSD has improved
dramatically. The largest change is a revamped virtual memory
system with a merged VM/file buffer cache that not only increases
performance, but reduces FreeBSD's memory footprint, making a 5MB
configuration a more acceptable minimum. Other enhancements include
full NIS client and server support, transaction TCP support,
dial-on-demand PPP, an improved SCSI subsystem, early ISDN support,
support for FDDI and Fast Ethernet (100Mbit) adapters, improved
support for the Adaptec 2940 (WIDE and narrow) and many hundreds of
bug fixes.</para>
<para>Since our release of FreeBSD 2.0 in January of 95, the performance,
feature set, and stability of FreeBSD has improved dramatically. The
largest change is a revamped virtual memory system with a merged VM/file
buffer cache that not only increases performance, but reduces FreeBSD's
memory footprint, making a 5MB configuration a more acceptable minimum.
Other enhancements include full NIS client and server support,
transaction TCP support, dial-on-demand PPP, an improved SCSI subsystem,
early ISDN support, support for FDDI and Fast Ethernet (100Mbit)
adapters, improved support for the Adaptec 2940 (WIDE and narrow) and
many hundreds of bug fixes.</para>
<para>We have also taken the comments and suggestions of many of our
users to heart and have attempted to provide what we hope is a more
sane and easily understood installation process. Your feedback on
this (constantly evolving) process is especially welcome!</para>
<para>We have also taken the comments and suggestions of many of our users
to heart and have attempted to provide what we hope is a more sane and
easily understood installation process. Your feedback on this
(constantly evolving) process is especially welcome!</para>
<para>In addition to the base distributions, FreeBSD offers a new
ported software collection with hundreds of commonly sought-after
programs. At the end of August 1998 there were more than 1700 ports!
The list of ports ranges from http (WWW) servers, to games,
languages, editors and almost everything in between. The entire
ports collection requires approximately 26MB of storage, all ports
being expressed as &ldquo;deltas&rdquo; to their original sources. This
makes it much easier for us to update ports, and greatly reduces
the disk space demands made by the older 1.0 ports collection. To
compile a port, you simply change to the directory of the program
you wish to install, type <command>make all</command> followed by <command>make install</command>
after successful compilation and let the system do the rest. The
full original distribution for each port you build is retrieved
dynamically off the CDROM or a local ftp site, so you need only
enough disk space to build the ports you want. (Almost) every port
is also provided as a pre-compiled &ldquo;package&rdquo; which can be installed
with a simple command (pkg_add) by those who do not wish to compile
their own ports from source.</para>
<para>A number of additional documents which you may find very helpful
in the process of installing and using FreeBSD may now also be found
in the <filename>/usr/share/doc</filename> directory on any machine
running FreeBSD 2.1 or later. You may view the locally installed
manuals with any HTML capable browser using the following
URLs:</para>
<para>In addition to the base distributions, FreeBSD offers a new ported
software collection with hundreds of commonly sought-after programs. At
the end of August 1998 there were more than 1700 ports! The list of
ports ranges from http (WWW) servers, to games, languages, editors and
almost everything in between. The entire ports collection requires
approximately 26MB of storage, all ports being expressed as
&ldquo;deltas&rdquo; to their original sources. This makes it much
easier for us to update ports, and greatly reduces the disk space
demands made by the older 1.0 ports collection. To compile a port, you
simply change to the directory of the program you wish to install, type
<command>make all</command> followed by <command>make install</command>
after successful compilation and let the system do the rest. The full
original distribution for each port you build is retrieved dynamically
off the CDROM or a local ftp site, so you need only enough disk space to
build the ports you want. (Almost) every port is also provided as a
pre-compiled &ldquo;package&rdquo; which can be installed with a simple
command (pkg_add) by those who do not wish to compile their own ports
from source.</para>
<para>A number of additional documents which you may find very helpful in
the process of installing and using FreeBSD may now also be found in the
<filename>/usr/share/doc</filename> directory on any machine running
FreeBSD 2.1 or later. You may view the locally installed manuals with
any HTML capable browser using the following URLs:</para>
<variablelist>
<varlistentry><term>The FreeBSD handbook</term>
<varlistentry>
<term>The FreeBSD handbook</term>
<listitem>
<para><ulink
URL="file:/usr/share/doc/handbook/handbook.html">file:/usr/share/doc/handbook/handbook.html</ulink></para>
</listitem>
</varlistentry>
<varlistentry><term>The FreeBSD FAQ</term>
<varlistentry>
<term>The FreeBSD FAQ</term>
<listitem>
<para><ulink
URL="file:/usr/share/doc/FAQ/FAQ.html">file:/usr/share/doc/FAQ/FAQ.html</ulink></para>
</listitem>
</varlistentry>
</variablelist>
<para>You can also visit the master (and most frequently updated)
copies at <ulink
URL="http://www.freebsd.org">http://www.freebsd.org</ulink>.</para>
<para>The core of FreeBSD does not contain DES code which would
inhibit its being exported outside the United States. There is an
add-on package to the core distribution, for use only in the United
States, that contains the programs that normally use DES. The
auxiliary packages provided separately can be used by anyone. A
freely (from outside the U.S.) exportable European distribution of
DES for our non-U.S. users also exists and is described in the
<ulink URL="../FAQ/FAQ.html">FreeBSD FAQ</ulink>.</para>
<para>If password security for FreeBSD is all you need, and you have
no requirement for copying encrypted passwords from different hosts
(Suns, DEC machines, etc) into FreeBSD password entries, then
FreeBSD's MD5 based security may be all you require! We feel that
our default security model is more than a match for DES, and without
any messy export issues to deal with. If you are outside (or even
inside) the U.S., give it a try!</para>
<para>The core of FreeBSD does not contain DES code which would inhibit
its being exported outside the United States. There is an add-on
package to the core distribution, for use only in the United States,
that contains the programs that normally use DES. The auxiliary
packages provided separately can be used by anyone. A freely (from
outside the U.S.) exportable European distribution of DES for our
non-U.S. users also exists and is described in the <ulink
URL="../FAQ/FAQ.html">FreeBSD FAQ</ulink>.</para>
<para>If password security for FreeBSD is all you need, and you have no
requirement for copying encrypted passwords from different hosts (Suns,
DEC machines, etc) into FreeBSD password entries, then FreeBSD's MD5
based security may be all you require! We feel that our default security
model is more than a match for DES, and without any messy export issues
to deal with. If you are outside (or even inside) the U.S., give it a
try!</para>
</sect1>
</chapter>
</chapter>
<!--
Local Variables:

1684
en_US.ISO_8859-1/books/handbook/kernelconfig/chapter.sgml
View file

File diff suppressed because it is too large Load diff

540
en_US.ISO_8859-1/books/handbook/kerneldebug/chapter.sgml
View file

@ -1,95 +1,87 @@
<chapter id="kerneldebug">
<chapter id="kerneldebug">
<title>Kernel Debugging</title>
<para><emphasis>Contributed by &a.paul; and &a.joerg;</emphasis></para>
<sect1>
<title>Debugging a Kernel Crash Dump with <command>kgdb</command></title>
<para>Here are some instructions for getting kernel debugging working
on a crash dump. They assume that you have enough swap space for a
crash dump. If you have multiple swap partitions and the first one
is too small to hold the dump, you can configure your kernel to use
an alternate dump device (in the <literal>config
kernel</literal> line), or you can specify an alternate using the
&man.dumpon.8; command. The best way to use &man.dumpon.8; is to set the <literal>dumpdev</literal> variable in
<para>Here are some instructions for getting kernel debugging working on a
crash dump. They assume that you have enough swap space for a crash
dump. If you have multiple swap partitions and the first one is too
small to hold the dump, you can configure your kernel to use an
alternate dump device (in the <literal>config kernel</literal> line), or
you can specify an alternate using the
&man.dumpon.8; command. The best way to use &man.dumpon.8; is to set
the <literal>dumpdev</literal> variable in
<filename>/etc/rc.conf</filename>. Typically you want to specify one of
the swap devices specified in <filename>/etc/fstab</filename>.
Dumps to non-swap devices, tapes for example,
are currently not supported. Config your kernel using
<command>config -g</command>. See <link linkend="kernelconfig">Kernel
Configuration</link> for
details on configuring the FreeBSD kernel.</para>
the swap devices specified in <filename>/etc/fstab</filename>. Dumps to
non-swap devices, tapes for example, are currently not supported. Config
your kernel using <command>config -g</command>. See <link
linkend="kernelconfig">Kernel Configuration</link> for details on
configuring the FreeBSD kernel.</para>
<para>Use the &man.dumpon.8; command to tell the kernel
where to dump to (note that this will have to be done after
configuring the partition in question as swap space via
&man.swapon.8;). This is normally arranged via
<filename>/etc/rc.conf</filename> and <filename>/etc/rc</filename>.
Alternatively, you can hard-code the dump device via the <literal>dump</literal>
clause in the <literal>config</literal> line of your kernel config file. This is
deprecated and should be used only if you want a crash dump from a
kernel that crashes during booting.</para>
<para>Use the &man.dumpon.8; command to tell the kernel where to dump to
(note that this will have to be done after configuring the partition in
question as swap space via &man.swapon.8;). This is normally arranged
via <filename>/etc/rc.conf</filename> and <filename>/etc/rc</filename>.
Alternatively, you can hard-code the dump device via the
<literal>dump</literal> clause in the <literal>config</literal> line of
your kernel config file. This is deprecated and should be used only if
you want a crash dump from a kernel that crashes during booting.</para>
<note>
<para>In the following, the term <command>kgdb</command> refers to
<command>gdb</command> run in &ldquo;kernel debug mode&rdquo;. This can be
accomplished by either starting the <command>gdb</command> with
the option <option>-k</option>, or by linking and starting it
under the name <command>kgdb</command>. This is not being done by
default, however, and the idea is basically deprecated since the
GNU folks do not like their tools to behave differently when
called by another name. This feature may well be discontinued in
further releases.</para>
<command>gdb</command> run in &ldquo;kernel debug mode&rdquo;. This
can be accomplished by either starting the <command>gdb</command> with
the option <option>-k</option>, or by linking and starting it under
the name <command>kgdb</command>. This is not being done by default,
however, and the idea is basically deprecated since the GNU folks do
not like their tools to behave differently when called by another
name. This feature may well be discontinued in further
releases.</para>
</note>
<para>When the kernel has been built make a copy of it, say
<filename>kernel.debug</filename>, and then run <command>strip
-d</command> on the original. Install the original as normal. You
may also install the unstripped kernel, but symbol table lookup time
for some programs will drastically increase, and since the whole
kernel is loaded entirely at boot time and cannot be swapped out
later, several megabytes of physical memory will be wasted.</para>
may also install the unstripped kernel, but symbol table lookup time for
some programs will drastically increase, and since the whole kernel is
loaded entirely at boot time and cannot be swapped out later, several
megabytes of physical memory will be wasted.</para>
<para>If you are testing a new kernel, for example by typing the new
kernel's name at the boot prompt, but need to boot a different one
in order to get your system up and running again, boot it only into
single user state using the <option>-s</option> flag at the boot
prompt, and then perform the following steps:</para>
kernel's name at the boot prompt, but need to boot a different one in
order to get your system up and running again, boot it only into single
user state using the <option>-s</option> flag at the boot prompt, and
then perform the following steps:</para>
<screen>&prompt.root; <userinput>fsck -p</userinput>
&prompt.root; <userinput>mount -a -t ufs</userinput> # so your file system for /var/crash is writable
&prompt.root; <userinput>savecore -N /kernel.panicked /var/crash</userinput>
&prompt.root; <userinput>exit</userinput> # ...to multi-user</screen>
<para>This instructs &man.savecore.8; to
use another kernel for symbol name extraction. It would otherwise
default to the currently running kernel and most likely not do
anything at all since the crash dump and the kernel symbols
differ.</para>
<para>This instructs &man.savecore.8; to use another kernel for symbol
name extraction. It would otherwise default to the currently running
kernel and most likely not do anything at all since the crash dump and
the kernel symbols differ.</para>
<para>Now, after a crash dump, go to
<filename>/sys/compile/WHATEVER</filename> and run <command>kgdb</command>. From <command>kgdb</command>
do:
<filename>/sys/compile/WHATEVER</filename> and run
<command>kgdb</command>. From <command>kgdb</command> do:
<screen><userinput>symbol-file kernel.debug</userinput>
<userinput>exec-file /var/crash/kernel.0</userinput>
<userinput>core-file /var/crash/vmcore.0</userinput></screen>
and voila, you can debug the crash dump using the kernel sources just
like you can for any other program.</para>
and voila, you can debug the crash dump using the
kernel sources just like you can for any other program.</para>
<para>Here is a script log of a <command>kgdb</command>
session illustrating the procedure. Long lines have been folded to
improve readability, and the lines are numbered for reference.
Despite this, it is a real-world error trace taken during the
development of the pcvt console driver.</para>
<para>Here is a script log of a <command>kgdb</command> session
illustrating the procedure. Long lines have been folded to improve
readability, and the lines are numbered for reference. Despite this, it
is a real-world error trace taken during the development of the pcvt
console driver.</para>
<screen> 1:Script started on Fri Dec 30 23:15:22 1994
2:&prompt.root; <userinput>cd /sys/compile/URIAH</userinput>
@ -172,68 +164,65 @@ Dumps to non-swap devices, tapes for example,
79:
80:Script done on Fri Dec 30 23:18:04 1994</screen>
<para>Comments to the above script:</para>
<variablelist>
<varlistentry><term>line 6:</term>
<listitem>
<para>This is a dump taken from within DDB (see below), hence
the panic comment &ldquo;because you said to!&rdquo;, and a rather
long stack trace; the initial reason for going into DDB has
been a page fault trap though.</para>
<varlistentry>
<term>line 6:</term>
<listitem>
<para>This is a dump taken from within DDB (see below), hence the
panic comment &ldquo;because you said to!&rdquo;, and a rather
long stack trace; the initial reason for going into DDB has been a
page fault trap though.</para>
</listitem>
</varlistentry>
<varlistentry><term>line 20:</term>
<varlistentry>
<term>line 20:</term>
<listitem>
<para>This is the location of function
<function>trap()</function> in the stack trace.</para>
<para>This is the location of function <function>trap()</function>
in the stack trace.</para>
</listitem>
</varlistentry>
<varlistentry><term>line 36:</term>
<varlistentry>
<term>line 36:</term>
<listitem>
<para>Force usage of a new stack frame; this is no longer
necessary now. The stack frames are supposed to point to
the right locations now, even in case of a trap. (I do not
have a new core dump handy &lt;g&gt;, my kernel has not
panicked for a rather long time.) From looking at the code
in source line 403, there is a high probability that either
the pointer access for &ldquo;tp&rdquo; was messed up, or the array
access was out of bounds.</para>
<para>Force usage of a new stack frame; this is no longer necessary
now. The stack frames are supposed to point to the right
locations now, even in case of a trap. (I do not have a new core
dump handy &lt;g&gt;, my kernel has not panicked for a rather long
time.) From looking at the code in source line 403, there is a
high probability that either the pointer access for
&ldquo;tp&rdquo; was messed up, or the array access was out of
bounds.</para>
</listitem>
</varlistentry>
<varlistentry><term>line 52:</term>
<varlistentry>
<term>line 52:</term>
<listitem>
<para>The pointer looks suspicious, but happens to be a valid
address.</para>
</listitem>
</varlistentry>
<varlistentry><term>line 56:</term>
<varlistentry>
<term>line 56:</term>
<listitem>
<para>However, it obviously points to garbage, so we have
found our error! (For those unfamiliar with that particular
piece of code: <literal>tp-&gt;t_line</literal>
refers to the line discipline of the console device here,
which must be a rather small integer number.)</para>
<para>However, it obviously points to garbage, so we have found our
error! (For those unfamiliar with that particular piece of code:
<literal>tp-&gt;t_line</literal> refers to the line discipline of
the console device here, which must be a rather small integer
number.)</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1>
@ -244,10 +233,8 @@ Dumps to non-swap devices, tapes for example,
option to the <command>ddd</command> command line you would use
normally. For example;</para>
<screen>&prompt.root; <userinput>ddd -k /var/crash/kernel.0 /var/crash/vmcore.0</userinput></screen>
<para>You should then be able to go about looking at the crash dump using
<command>ddd</command>'d graphical interface.</para>
</sect1>
@ -255,124 +242,115 @@ Dumps to non-swap devices, tapes for example,
<sect1>
<title>Post-mortem Analysis of a Dump</title>
<para>What do you do if a kernel dumped core but you did not expect
it, and it is therefore not compiled using <command>config
-g</command>? Not everything is lost here. Do not panic!</para>
<para>What do you do if a kernel dumped core but you did not expect it,
and it is therefore not compiled using <command>config -g</command>? Not
everything is lost here. Do not panic!</para>
<para>Of course, you still need to enable crash dumps. See above on
the options you have to specify in order to do this.</para>
<para>Of course, you still need to enable crash dumps. See above on the
options you have to specify in order to do this.</para>
<para>Go to your kernel compile directory, and edit the line
containing <literal>COPTFLAGS?=-O</literal>. Add the
<option>-g</option> option there (but <emphasis>do not</emphasis>
change anything on the level of optimization). If you do already
know roughly the probable location of the failing piece of code
(e.g., the <devicename>pcvt</devicename> driver in the example
above), remove all the object files for this code. Rebuild the
kernel. Due to the time stamp change on the Makefile, there will be
some other object files rebuild, for example
<para>Go to your kernel compile directory, and edit the line containing
<literal>COPTFLAGS?=-O</literal>. Add the <option>-g</option> option
there (but <emphasis>do not</emphasis> change anything on the level of
optimization). If you do already know roughly the probable location of
the failing piece of code (e.g., the <devicename>pcvt</devicename>
driver in the example above), remove all the object files for this code.
Rebuild the kernel. Due to the time stamp change on the Makefile, there
will be some other object files rebuild, for example
<filename>trap.o</filename>. With a bit of luck, the added
<option>-g</option> option will not change anything for the
generated code, so you will finally get a new kernel with similar
code to the faulting one but some debugging symbols. You should at
least verify the old and new sizes with the
&man.size.1; command. If there is a mismatch, you
probably need to give up here.</para>
<option>-g</option> option will not change anything for the generated
code, so you will finally get a new kernel with similar code to the
faulting one but some debugging symbols. You should at least verify the
old and new sizes with the
&man.size.1; command. If there is a mismatch, you probably need to
give up here.</para>
<para>Go and examine the dump as described above. The debugging
symbols might be incomplete for some places, as can be seen in the
stack trace in the example above where some functions are displayed
without line numbers and argument lists. If you need more debugging
symbols, remove the appropriate object files and repeat the
<command>kgdb</command> session until you know
enough.</para>
<para>All this is not guaranteed to work, but it will do it fine in
most cases.</para>
<para>Go and examine the dump as described above. The debugging symbols
might be incomplete for some places, as can be seen in the stack trace
in the example above where some functions are displayed without line
numbers and argument lists. If you need more debugging symbols, remove
the appropriate object files and repeat the <command>kgdb</command>
session until you know enough.</para>
<para>All this is not guaranteed to work, but it will do it fine in most
cases.</para>
</sect1>
<sect1>
<title>On-line Kernel Debugging Using DDB</title>
<para>While <command>kgdb</command> as an offline debugger
provides a very high level of user interface, there are some things
it cannot do. The most important ones being breakpointing and
single-stepping kernel code.</para>
<para>While <command>kgdb</command> as an offline debugger provides a very
high level of user interface, there are some things it cannot do. The
most important ones being breakpointing and single-stepping kernel
code.</para>
<para>If you need to do low-level debugging on your kernel, there is
an on-line debugger available called DDB. It allows to setting
<para>If you need to do low-level debugging on your kernel, there is an
on-line debugger available called DDB. It allows to setting
breakpoints, single-steping kernel functions, examining and changing
kernel variables, etc. However, it cannot access kernel source
files, and only has access to the global and static symbols, not to
the full debug information like <command>kgdb</command>.</para>
kernel variables, etc. However, it cannot access kernel source files,
and only has access to the global and static symbols, not to the full
debug information like <command>kgdb</command>.</para>
<para>To configure your kernel to include DDB, add the option line
<programlisting>
options DDB</programlisting> to your config file, and rebuild. (See <link
linkend="kernelconfig">Kernel Configuration</link> for details on configuring the
FreeBSD kernel.</para>
options DDB</programlisting>
to your config file, and rebuild. (See <link
linkend="kernelconfig">Kernel Configuration</link> for details on
configuring the FreeBSD kernel.</para>
<note>
<para>Note that if you have an older version of the boot blocks,
your debugger symbols might not be loaded at all. Update the boot
blocks; the recent ones load the DDB symbols
automagically.)</para>
<para>Note that if you have an older version of the boot blocks, your
debugger symbols might not be loaded at all. Update the boot blocks;
the recent ones load the DDB symbols automagically.)</para>
</note>
<para>Once your DDB kernel is running, there are several ways to enter
DDB. The first, and earliest way is to type the boot flag
<option>-d</option> right at the boot prompt. The kernel will start
up in debug mode and enter DDB prior to any device probing. Hence
you can even debug the device probe/attach functions.</para>
<option>-d</option> right at the boot prompt. The kernel will start up
in debug mode and enter DDB prior to any device probing. Hence you can
even debug the device probe/attach functions.</para>
<para>The second scenario is a hot-key on the keyboard, usually
Ctrl-Alt-ESC. For syscons, this can be remapped; some of the
distributed maps do this, so watch out. There is an option available
for serial consoles that allows the use of a serial line BREAK on
the console line to enter DDB (<literal>options
BREAK_TO_DEBUGGER</literal> in the kernel config file). It is
not the default since there are a lot of crappy serial adapters
around that gratuitously generate a BREAK condition, for example
when pulling the cable.</para>
for serial consoles that allows the use of a serial line BREAK on the
console line to enter DDB (<literal>options BREAK_TO_DEBUGGER</literal>
in the kernel config file). It is not the default since there are a lot
of crappy serial adapters around that gratuitously generate a BREAK
condition, for example when pulling the cable.</para>
<para>The third way is that any panic condition will branch to DDB if
the kernel is configured to use it. For this reason, it is not
wise to configure a kernel with DDB for a machine running
unattended.</para>
<para>The DDB commands roughly resemble some <command>gdb</command> commands. The first thing you probably
need to do is to set a breakpoint:</para>
<para>The third way is that any panic condition will branch to DDB if the
kernel is configured to use it. For this reason, it is not wise to
configure a kernel with DDB for a machine running unattended.</para>
<para>The DDB commands roughly resemble some <command>gdb</command>
commands. The first thing you probably need to do is to set a
breakpoint:</para>
<screen><userinput>b function-name</userinput>
<userinput>b address</userinput></screen>
<para>Numbers are taken hexadecimal by default, but to make them distinct
from symbol names; hexadecimal numbers starting with the letters
<literal>a-f</literal> need to be preceded with <literal>0x</literal>
(this is optional for other numbers). Simple expressions are allowed,
for example: <literal>function-name + 0x103</literal>.</para>
<para>Numbers are taken hexadecimal by default, but to make them
distinct from symbol names; hexadecimal numbers starting with the
letters <literal>a-f</literal> need to be preceded with
<literal>0x</literal> (this is optional for other numbers). Simple
expressions are allowed, for example: <literal>function-name +
0x103</literal>.</para>
<para>To continue the operation of an interrupted kernel, simply type:</para>
<para>To continue the operation of an interrupted kernel, simply
type:</para>
<screen><userinput>c</userinput></screen>
<para>To get a stack trace, use:</para>
<screen><userinput>trace</userinput></screen>
<note>
<para>Note that when entering DDB via a hot-key, the kernel is
currently servicing an interrupt, so the stack trace might be not
of much use for you.</para>
<para>Note that when entering DDB via a hot-key, the kernel is currently
servicing an interrupt, so the stack trace might be not of much use
for you.</para>
</note>
<para>If you want to remove a breakpoint, use</para>
@ -381,178 +359,143 @@ options DDB</programlisting> to your config file, and rebuild. (See <link
<screen><userinput>del</userinput>
<userinput>del address-expression</userinput></screen>
<para>The first form will be accepted immediately after
a breakpoint hit, and deletes the current breakpoint. The second
form can remove any breakpoint, but you need to specify the exact
address; this can be obtained from:</para>
<para>The first form will be accepted immediately after a breakpoint hit,
and deletes the current breakpoint. The second form can remove any
breakpoint, but you need to specify the exact address; this can be
obtained from:</para>
<screen><userinput>show b</userinput></screen>
<para>To single-step the kernel, try:</para>
<screen><userinput>s</userinput></screen>
<para>This will step into functions, but you can make
DDB trace them until the matching return statement is reached by:</para>
<para>This will step into functions, but you can make DDB trace them until
the matching return statement is reached by:</para>
<screen><userinput>n</userinput></screen>
<note>
<para>This is different from <command>gdb</command>'s <command>next</command>
statement; it is like <command>gdb</command>'s <command>finish</command>.</para>
<para>This is different from <command>gdb</command>'s
<command>next</command> statement; it is like <command>gdb</command>'s
<command>finish</command>.</para>
</note>
<para>To examine data from memory, use (for example):
<screen><userinput>x/wx 0xf0133fe0,40</userinput>
<userinput>x/hd db_symtab_space</userinput>
<userinput>x/bc termbuf,10</userinput>
<userinput>x/s stringbuf</userinput></screen>
for word/halfword/byte access, and
hexadecimal/decimal/character/ string display. The number after the
comma is the object count. To display the next 0x10 items, simply
use:</para>
for word/halfword/byte access, and hexadecimal/decimal/character/ string
display. The number after the comma is the object count. To display
the next 0x10 items, simply use:</para>
<screen><userinput>x ,10</userinput></screen>
<para>Similarly, use
<screen><userinput>x/ia foofunc,10</userinput></screen>
to disassemble the first 0x10 instructions of
<function>foofunc</function>, and display them along with
their offset from the beginning of <function>foofunc</function>.</para>
<function>foofunc</function>, and display them along with their offset
from the beginning of <function>foofunc</function>.</para>
<para>To modify memory, use the write command:</para>
<screen><userinput>w/b termbuf 0xa 0xb 0</userinput>
<userinput>w/w 0xf0010030 0 0</userinput></screen>
<para>The command modifier
(<literal>b</literal>/<literal>h</literal>/<literal>w</literal>) specifies the size of the data to be
written, the first following expression is the address to write to
and the remainder is interpreted as data to write to successive
memory locations.</para>
(<literal>b</literal>/<literal>h</literal>/<literal>w</literal>)
specifies the size of the data to be written, the first following
expression is the address to write to and the remainder is interpreted
as data to write to successive memory locations.</para>
<para>If you need to know the current registers, use:</para>
<screen><userinput>show reg</userinput></screen>
<para>Alternatively, you can display a single register
value by e.g.
<para>Alternatively, you can display a single register value by e.g.
<screen><userinput>p $eax</userinput></screen>
and modify it by:</para>
<screen><userinput>set $eax new-value</userinput></screen>
<para>Should you need to call some kernel functions from DDB, simply
say:</para>
<screen><userinput>call func(arg1, arg2, ...)</userinput></screen>
<para>The return value will be printed.</para>
<para>For a &man.ps.1; style summary of all running
processes, use:</para>
<para>For a &man.ps.1; style summary of all running processes, use:</para>
<screen><userinput>ps</userinput></screen>
<para>Now you have now examined why your kernel failed, and you wish
to reboot. Remember that, depending on the severity of previous
malfunctioning, not all parts of the kernel might still be working
as expected. Perform one of the following actions to shut down and
reboot your system:</para>
<para>Now you have now examined why your kernel failed, and you wish to
reboot. Remember that, depending on the severity of previous
malfunctioning, not all parts of the kernel might still be working as
expected. Perform one of the following actions to shut down and reboot
your system:</para>
<screen><userinput>call diediedie()</userinput></screen>
<para>This will cause your kernel to dump core and reboot, so you can
later analyze the core on a higher level with kgdb. This command
usually must be followed by another <command>continue</command> statement. There is now an alias for
this: <command>panic</command>.</para>
usually must be followed by another <command>continue</command>
statement. There is now an alias for this:
<command>panic</command>.</para>
<screen><userinput>call boot(0)</userinput></screen>
<para>Which might be a good way to cleanly shut down the
running system, <function>sync()</function> all disks, and finally
reboot. As long as the disk and file system interfaces of the
kernel are not damaged, this might be a good way for an almost clean
shutdown.</para>
<para>Which might be a good way to cleanly shut down the running system,
<function>sync()</function> all disks, and finally reboot. As long as
the disk and file system interfaces of the kernel are not damaged, this
might be a good way for an almost clean shutdown.</para>
<screen><userinput>call cpu_reset()</userinput></screen>
<para>is the final way out of disaster and almost the
same as hitting the Big Red Button.</para>
<para>is the final way out of disaster and almost the same as hitting the
Big Red Button.</para>
<para>If you need a short command summary, simply type:</para>
<screen><userinput>help</userinput></screen>
<para>However, it is highly recommended to have a
printed copy of the &man.ddb.4; manual page
ready for a debugging session. Remember that it is hard to read the
on-line manual while single-stepping the kernel.</para>
<para>However, it is highly recommended to have a printed copy of the
&man.ddb.4; manual page ready for a debugging
session. Remember that it is hard to read the on-line manual while
single-stepping the kernel.</para>
</sect1>
<sect1>
<title>On-line Kernel Debugging Using Remote GDB</title>
<para>This feature has been supported since FreeBSD 2.2, and it's
actually a very neat one.</para>
<para>This feature has been supported since FreeBSD 2.2, and it's actually
a very neat one.</para>
<para>GDB has already supported <emphasis>remote debugging</emphasis>
for a long time. This is done using a very simple protocol along a
serial line. Unlike the other methods described above, you will
need two machines for doing this. One is the host providing the
debugging environment, including all the sources, and a copy of the
kernel binary with all the symbols in it, and the other one is the
target machine that simply runs a similar copy of the very same
kernel (but stripped of the debugging information).</para>
<para>GDB has already supported <emphasis>remote debugging</emphasis> for
a long time. This is done using a very simple protocol along a serial
line. Unlike the other methods described above, you will need two
machines for doing this. One is the host providing the debugging
environment, including all the sources, and a copy of the kernel binary
with all the symbols in it, and the other one is the target machine that
simply runs a similar copy of the very same kernel (but stripped of the
debugging information).</para>
<para>You should configure the kernel in question with <command>config
-g</command>, include <option>DDB</option> into the
configuration, and compile it as usual. This gives a large blurb of
a binary, due to the debugging information. Copy this kernel to the
target machine, strip the debugging symbols off with <command>strip
-x</command>, and boot it using the <option>-d</option> boot
option. Connect the first serial line of the target machine to any
serial line of the debugging host. Now, on the debugging machine,
go to the compile directory of the target kernel, and start gdb:</para>
-g</command>, include <option>DDB</option> into the configuration, and
compile it as usual. This gives a large blurb of a binary, due to the
debugging information. Copy this kernel to the target machine, strip
the debugging symbols off with <command>strip -x</command>, and boot it
using the <option>-d</option> boot option. Connect the first serial
line of the target machine to any serial line of the debugging host.
Now, on the debugging machine, go to the compile directory of the target
kernel, and start gdb:</para>
<screen>&prompt.user; <userinput>gdb -k kernel</userinput>
GDB is free software and you are welcome to distribute copies of it
@ -562,94 +505,77 @@ GDB 4.16 (i386-unknown-freebsd),
Copyright 1996 Free Software Foundation, Inc...
<prompt>(kgdb)</prompt> </screen>
<para>Initialize the remote debugging session (assuming the first
serial port is being used) by:</para>
<para>Initialize the remote debugging session (assuming the first serial
port is being used) by:</para>
<screen><prompt>(kgdb)</prompt> <userinput>target remote /dev/cuaa0</userinput></screen>
<para>Now, on the target host (the one that entered DDB right before
even starting the device probe), type:</para>
<para>Now, on the target host (the one that entered DDB right before even
starting the device probe), type:</para>
<screen>Debugger("Boot flags requested debugger")
Stopped at Debugger+0x35: movb $0, edata+0x51bc
<prompt>db&gt;</prompt> <userinput>gdb</userinput></screen>
<para>DDB will respond with:</para>
<screen>Next trap will enter GDB remote protocol mode</screen>
<para>Every time you type <command>gdb</command>, the mode will be toggled between
remote GDB and local DDB. In order to force a next trap
immediately, simply type <command>s</command> (step). Your hosting GDB will now
gain control over the target kernel:</para>
<para>Every time you type <command>gdb</command>, the mode will be toggled
between remote GDB and local DDB. In order to force a next trap
immediately, simply type <command>s</command> (step). Your hosting GDB
will now gain control over the target kernel:</para>
<screen>Remote debugging using /dev/cuaa0
Debugger (msg=0xf01b0383 "Boot flags requested debugger")
at ../../i386/i386/db_interface.c:257
<prompt>(kgdb)</prompt></screen>
<para>You can use this session almost as any other GDB session, including
full access to the source, running it in gud-mode inside an Emacs window
(which gives you an automatic source code display in another Emacs
window) etc.</para>
<para>You can use this session almost as any other GDB session,
including full access to the source, running it in gud-mode inside
an Emacs window (which gives you an automatic source code display in
another Emacs window) etc.</para>
<para>Remote GDB can also be used to debug LKMs. First build the LKM
with debugging symbols:</para>
<para>Remote GDB can also be used to debug LKMs. First build the LKM with
debugging symbols:</para>
<screen>&prompt.root; <userinput>cd /usr/src/lkm/linux</userinput>
&prompt.root; <userinput>make clean; make COPTS=-g</userinput></screen>
<para>Then install this version of the module on the target machine,
load it and use <command>modstat</command> to find out
where it was loaded:</para>
<para>Then install this version of the module on the target machine, load
it and use <command>modstat</command> to find out where it was
loaded:</para>
<screen>&prompt.root; <userinput>linux</userinput>
&prompt.root; <userinput>modstat</userinput>
Type Id Off Loadaddr Size Info Rev Module Name
EXEC 0 4 f5109000 001c f510f010 1 linux_mod</screen>
<para>Take the load address of the module and add 0x20 (probably to
account for the a.out header). This is the address that the module
code was relocated to. Use the <command>add-symbol-file</command> command in GDB to tell the
debugger about the module:</para>
account for the a.out header). This is the address that the module code
was relocated to. Use the <command>add-symbol-file</command> command in
GDB to tell the debugger about the module:</para>
<screen><prompt>(kgdb)</prompt> <userinput>add-symbol-file /usr/src/lkm/linux/linux_mod.o 0xf5109020</userinput>
add symbol table from file "/usr/src/lkm/linux/linux_mod.o" at
text_addr = 0xf5109020? (y or n) <userinput>y</userinput>
<prompt>(kgdb)</prompt></screen>
<para>You now have access to all the symbols in the LKM.</para>
</sect1>
<sect1>
<title>Debugging a Console Driver</title>
<para>Since you need a console driver to run DDB on, things are more
complicated if the console driver itself is failing. You might
remember the use of a serial console (either with modified boot
blocks, or by specifying <option>-h</option> at the <prompt>Boot:</prompt> prompt), and hook up a standard terminal
onto your first serial port. DDB works on any configured console
driver, of course also on a serial console.</para>
complicated if the console driver itself is failing. You might remember
the use of a serial console (either with modified boot blocks, or by
specifying <option>-h</option> at the <prompt>Boot:</prompt> prompt),
and hook up a standard terminal onto your first serial port. DDB works
on any configured console driver, of course also on a serial
console.</para>
</sect1>
</chapter>
</chapter>
<!--
Local Variables:

175
en_US.ISO_8859-1/books/handbook/kernelopts/chapter.sgml
View file

@ -1,53 +1,50 @@
<chapter id="kernelopts">
<chapter id="kernelopts">
<title>Adding New Kernel Configuration Options</title>
<para><emphasis>Contributed by &a.joerg;</emphasis></para>
<note>
<para>You should be familiar with the section about <link
linkend="kernelconfig">kernel configuration</link>
before reading here.</para>
linkend="kernelconfig">kernel configuration</link> before reading
here.</para>
</note>
<sect1>
<title>What's a <emphasis>Kernel Option</emphasis>, Anyway?</title>
<para>The use of kernel options is basically described in the <link
linkend="kernelconfig-options">kernel configuration</link>
section. There's also an explanation of &ldquo;historic&rdquo; and
&ldquo;new-style&rdquo; options. The ultimate goal is to eventually turn all
the supported options in the kernel into new-style ones, so for
people who correctly did a <command>make depend</command>
in their kernel compile directory after running
&man.config.8;, the build process will automatically
pick up modified options, and only recompile those files where it is
necessary. Wiping out the old compile directory on each run of
&man.config.8; as it is still done now can then be
eliminated again.</para>
linkend="kernelconfig-options">kernel configuration</link> section.
There's also an explanation of &ldquo;historic&rdquo; and
&ldquo;new-style&rdquo; options. The ultimate goal is to eventually
turn all the supported options in the kernel into new-style ones, so for
people who correctly did a <command>make depend</command> in their
kernel compile directory after running
&man.config.8;, the build process will automatically pick up modified
options, and only recompile those files where it is necessary. Wiping
out the old compile directory on each run of &man.config.8; as it is
still done now can then be eliminated again.</para>
<para>Basically, a kernel option is nothing else than the definition
of a C preprocessor macro for the kernel compilation process. To
make the build truly optional, the corresponding part of the kernel
source (or kernel <filename>.h</filename> file) must be written with
the option concept in mind, i.e. the default must have been made
overridable by the config option. This is usually done with
something like:</para>
<para>Basically, a kernel option is nothing else than the definition of a
C preprocessor macro for the kernel compilation process. To make the
build truly optional, the corresponding part of the kernel source (or
kernel <filename>.h</filename> file) must be written with the option
concept in mind, i.e. the default must have been made overridable by the
config option. This is usually done with something like:</para>
<programlisting>
#ifndef THIS_OPTION
#define THIS_OPTION (some_default_value)
#endif /* THIS_OPTION */</programlisting>
<para>This way, an administrator mentioning another value for the
option in his config file will take the default out of effect, and
replace it with his new value. Clearly, the new value will be
substituted into the source code during the preprocessor run, so it
must be a valid C expression in whatever context the default value
would have been used.</para>
<para>This way, an administrator mentioning another value for the option
in his config file will take the default out of effect, and replace it
with his new value. Clearly, the new value will be substituted into the
source code during the preprocessor run, so it must be a valid C
expression in whatever context the default value would have been
used.</para>
<para>It is also possible to create value-less options that simply
enable or disable a particular piece of code by embracing it
in</para>
<para>It is also possible to create value-less options that simply enable
or disable a particular piece of code by embracing it in</para>
<programlisting>
#ifdef THAT_OPTION
@ -56,15 +53,14 @@
#endif</programlisting>
<para>Simply mentioning <literal>THAT_OPTION</literal> in the config
file (with or without any value) will then turn on the corresponding
piece of code.</para>
<para>Simply mentioning <literal>THAT_OPTION</literal> in the config file
(with or without any value) will then turn on the corresponding piece of
code.</para>
<para>People familiar with the C language will immediately recognize
that everything could be counted as a &ldquo;config option&rdquo; where there
is at least a single <literal>#ifdef</literal>
referencing it... However, it's unlikely that many people would
put</para>
<para>People familiar with the C language will immediately recognize that
everything could be counted as a &ldquo;config option&rdquo; where there
is at least a single <literal>#ifdef</literal> referencing it...
However, it's unlikely that many people would put</para>
<programlisting>
options notyet,notdef</programlisting>
@ -72,38 +68,40 @@ options notyet,notdef</programlisting>
<para>in their config file, and then wonder why the kernel compilation
falls over. <!-- smiley -->:-)</para>
<para>Clearly, using arbitrary names for the options makes it very
hard to track their usage throughout the kernel source tree. That
is the rationale behind the <emphasis>new-style</emphasis> option
scheme, where each option goes into a separate
<filename>.h</filename> file in the kernel compile directory, which
is by convention named
<para>Clearly, using arbitrary names for the options makes it very hard to
track their usage throughout the kernel source tree. That is the
rationale behind the <emphasis>new-style</emphasis> option scheme, where
each option goes into a separate <filename>.h</filename> file in the
kernel compile directory, which is by convention named
<filename>opt_<replaceable>foo</replaceable>.h</filename>. This way,
the usual Makefile dependencies could be applied, and <command>make</command> can determine what needs to be recompiled
once an option has been changed.</para>
the usual Makefile dependencies could be applied, and
<command>make</command> can determine what needs to be recompiled once
an option has been changed.</para>
<para>The old-style option mechanism still has one advantage for local
options or maybe experimental options that have a short anticipated
lifetime: since it is easy to add a new <literal>#ifdef</literal> to the kernel source, this has already
made it a kernel config option. In this case, the administrator
using such an option is responsible himself for knowing about its
implications (and maybe manually forcing the recompilation of parts
of his kernel). Once the transition of all supported options has
been done, &man.config.8; will warn whenever an
unsupported option appears in the config file, but it will
nevertheless include it into the kernel Makefile.</para>
lifetime: since it is easy to add a new <literal>#ifdef</literal> to the
kernel source, this has already made it a kernel config option. In this
case, the administrator using such an option is responsible himself for
knowing about its implications (and maybe manually forcing the
recompilation of parts of his kernel). Once the transition of all
supported options has been done, &man.config.8; will warn whenever an
unsupported option appears in the config file, but it will nevertheless
include it into the kernel Makefile.</para>
</sect1>
<sect1>
<title>Now What Do I Have to Do for it?</title>
<para>First, edit <filename>sys/conf/options</filename> (or
<filename>sys/i386/conf/options.<replaceable>&lt;arch&gt;</replaceable></filename>, e. g. <filename>sys/i386/conf/options.i386</filename>), and select an <filename>opt_<replaceable>foo</replaceable>.h</filename> file where your new option would best go into.</para>
<filename>sys/i386/conf/options.<replaceable>&lt;arch&gt;</replaceable></filename>,
e. g. <filename>sys/i386/conf/options.i386</filename>), and select an
<filename>opt_<replaceable>foo</replaceable>.h</filename> file where
your new option would best go into.</para>
<para>If there is already something that comes close to the purpose of
the new option, pick this. For example, options modifying the
overall behaviour of the SCSI subsystem can go into
<para>If there is already something that comes close to the purpose of the
new option, pick this. For example, options modifying the overall
behaviour of the SCSI subsystem can go into
<filename>opt_scsi.h</filename>. By default, simply mentioning an
option in the appropriate option file, say <literal>FOO</literal>,
implies its value will go into the corresponding file
@ -114,51 +112,38 @@ options notyet,notdef</programlisting>
<filename>opt_<replaceable>foo</replaceable>.h</filename> already
available for the intended new option, invent a new name. Make it
meaningful, and comment the new section in the
<filename>options[<replaceable>.&lt;arch&gt;</replaceable>]</filename> file. &man.config.8; will automagically pick up the change, and create that file next time it is run. Most options should go in a header file by themselves..</para>
<filename>options[<replaceable>.&lt;arch&gt;</replaceable>]</filename>
file. &man.config.8; will automagically pick up the change, and create
that file next time it is run. Most options should go in a header file
by themselves..</para>
<para>Packing too many options into a single
<filename>opt_<replaceable>foo</replaceable>.h</filename> will cause
too many kernel files to be rebuilt when one of the options has been
changed in the config file.</para>
<filename>opt_<replaceable>foo</replaceable>.h</filename> will cause too
many kernel files to be rebuilt when one of the options has been changed
in the config file.</para>
<para>Finally, find out which kernel files depend on the new option.
Unless you have just invented your option, and it does not exist
anywhere yet,
anywhere yet, <screen>&prompt.user; <userinput>find /usr/src/sys -name
type f | xargs fgrep NEW_OPTION</userinput></screen> is your friend
in finding them. Go and edit all those files, and add <programlisting>
#include "opt_foo.h"</programlisting> <emphasis>on top</emphasis>,
before all the <literal>#include &lt;xxx.h&gt;</literal> stuff. This
sequence is most important as the options could override defaults from
the regular include files, if the defaults are of the form
<programlisting> #ifndef NEW_OPTION #define NEW_OPTION (something)
#endif</programlisting> in the regular header.</para>
<screen>&prompt.user; <userinput>find /usr/src/sys -name type f | xargs fgrep NEW_OPTION</userinput></screen>
is your friend in finding them. Go and edit all those files,
and add
<programlisting>
#include "opt_foo.h"</programlisting>
<emphasis>on top</emphasis>, before all the <literal>#include &lt;xxx.h&gt;</literal> stuff. This sequence
is most important as the options could override defaults from the
regular include files, if the defaults are of the form
<programlisting>
#ifndef NEW_OPTION
#define NEW_OPTION (something)
#endif</programlisting>
in the regular header.</para>
<para>Adding an option that overrides something in a system header
file (i.e., a file sitting in
<filename>/usr/include/sys/</filename>) is almost always a mistake.
<para>Adding an option that overrides something in a system header file
(i.e., a file sitting in <filename>/usr/include/sys/</filename>) is
almost always a mistake.
<filename>opt_<replaceable>foo</replaceable>.h</filename> cannot be
included into those files since it would break the headers more
seriously, but if it is not included, then places that include it
may get an inconsistent value for the option. Yes, there are
precedents for this right now, but that does not make them more
correct.</para>
seriously, but if it is not included, then places that include it may
get an inconsistent value for the option. Yes, there are precedents for
this right now, but that does not make them more correct.</para>
</sect1>
</chapter>
</chapter>
<!--
Local Variables:

221
en_US.ISO_8859-1/books/handbook/l10n/chapter.sgml
View file

@ -1,7 +1,6 @@
<chapter id="l10n">
<chapter id="l10n">
<title>Localization</title>
<sect1 id="russian">
<title>Russian Language (KOI8-R encoding)</title>
@ -12,20 +11,18 @@
URL="http://www.nagual.pp.ru/~ache/koi8.html">KOI8-R References
(Russian Net Character Set)</ulink>.</para>
<sect2 id="russian-console">
<title>Console Setup</title>
<procedure>
<step>
<para>Add following line to your kernel configuration file:
<programlisting>
options "SC_MOUSE_CHAR=0x03"</programlisting> to move character
codes used for mouse cursor off KOI8-R pseudographics
range.</para>
options "SC_MOUSE_CHAR=0x03"</programlisting>
to move character codes used for mouse cursor off KOI8-R
pseudographics range.</para>
</step>
<step>
@ -42,35 +39,31 @@ font8x8=cp866-8x8</programlisting>
<note>
<para>^[ means that real ESC character must be entered into
<filename>/etc/rc.conf</filename>, not just ^[
string.</para>
<filename>/etc/rc.conf</filename>, not just ^[ string.</para>
</note>
<para>This tuning means KOI8-R keyboard with Alternative
screen font mapped to KOI8-R encoding to preserve
pseudographics, <literal>Gray Delete</literal>
key remapped to match Russian &man.termcap.5; entry for FreeBSD
console.</para>
<para>This tuning means KOI8-R keyboard with Alternative screen font
mapped to KOI8-R encoding to preserve pseudographics,
<literal>Gray Delete</literal> key remapped to match Russian
&man.termcap.5; entry for
FreeBSD console.</para>
<para>RUS/LAT switch will be <literal>CapsLock</literal>. Old CapsLock function still
available via <literal>Shift+CapsLock</literal>.
CapsLock LED will indicate RUS mode, not CapsLock
mode.</para>
<para>RUS/LAT switch will be <literal>CapsLock</literal>. Old
CapsLock function still available via
<literal>Shift+CapsLock</literal>. CapsLock LED will indicate RUS
mode, not CapsLock mode.</para>
</step>
<step>
<para>For each <literal>ttyv?</literal> entry in
<filename>/etc/ttys</filename> change terminal type from
<literal>cons25</literal> to <literal>cons25r</literal>, i.e. each entry should looks
like:</para>
<literal>cons25</literal> to <literal>cons25r</literal>, i.e. each
entry should looks like:</para>
<programlisting>
ttyv0 "/usr/libexec/getty Pc" cons25r on secure</programlisting>
</step>
</procedure>
</sect2>
<sect2 id="russian-locale">
@ -80,32 +73,28 @@ ttyv0 "/usr/libexec/getty Pc" cons25r on secure</programlisting>
for locale setup:</para>
<itemizedlist>
<listitem>
<para><envar>LANG</envar> for POSIX
&man.setlocale.3; family functions;</para>
<para><envar>LANG</envar> for POSIX &man.setlocale.3; family
functions;</para>
</listitem>
<listitem>
<para><envar>MM_CHARSET</envar> for applications MIME
chararter set.</para>
<para><envar>MM_CHARSET</envar> for applications MIME chararter
set.</para>
</listitem>
</itemizedlist>
<para>The best way is using <filename>/etc/login.conf</filename>
<literal>russian</literal> user's login class in
&man.passwd.5; entry login class
position. See &man.login.conf.5; for
details.</para>
&man.passwd.5; entry login class position. See &man.login.conf.5;
for details.</para>
<sect3 id="russian-class">
<title>Login Class Method</title>
<para>First of all check your <filename>/etc/login.conf</filename>
have <literal>russian</literal> login class, this
entry may looks like:</para>
have <literal>russian</literal> login class, this entry may looks
like:</para>
<programlisting>
russian:Russian Users Accounts:\
@ -113,82 +102,71 @@ russian:Russian Users Accounts:\
:lang=ru_RU.KOI8-R:\
:tc=default:</programlisting>
<sect4>
<title>How to do it with &man.vipw.8;</title>
<para>If you use &man.vipw.8; for adding new
users, <filename>/etc/master.passwd</filename> entry should
looks like:</para>
<para>If you use &man.vipw.8; for adding new users,
<filename>/etc/master.passwd</filename> entry should looks
like:</para>
<programlisting>
user:password:1111:11:russian:0:0:User Name:/home/user:/bin/csh</programlisting>
</sect4>
<sect4>
<title>How to do it with &man.adduser.8;</title>
<para>If you use &man.adduser.8; for adding new
users:</para>
<itemizedlist>
<para>If you use &man.adduser.8; for adding new users:</para>
<itemizedlist>
<listitem>
<para>Set
<programlisting>
defaultclass = russian</programlisting> in
<filename>/etc/adduser.conf</filename> (you must enter
<literal>default</literal> class for all
non-Russian users in this case);</para>
defaultclass = russian</programlisting>
in <filename>/etc/adduser.conf</filename> (you must enter
<literal>default</literal> class for all non-Russian users in
this case);</para>
</listitem>
<listitem>
<para>Alternative variant will be answering <literal>russian</literal> each time when you see
<para>Alternative variant will be answering
<literal>russian</literal> each time when you see
<screen><prompt>Enter login class:</prompt> default []:</screen>
prompt from
&man.adduser.8;;</para>
prompt from &man.adduser.8;;</para>
</listitem>
<listitem>
<para>Another variant: call
<screen>&prompt.root; <userinput>adduser -class russian</userinput></screen>
for each Russian user
you want to add.</para>
for each Russian user you want to add.</para>
</listitem>
</itemizedlist>
</sect4>
<sect4>
<title>How to do it with &man.pw.8;</title>
<para>If you use &man.pw.8; for adding new users,
call it in this form:</para>
<para>If you use &man.pw.8; for adding new users, call it in this
form:</para>
<screen>&prompt.root; <userinput>pw useradd user_name -L russian</userinput></screen>
</sect4>
</sect3>
<sect3>
<title>Shell Startup Files Method</title>
<para>If you don't want to use
<link linkend="russian-class">login class method</link> for
some reasons, just set this
<link linkend="russian-env">two environment variables</link>
in the following shell startup files:</para>
<para>If you don't want to use <link linkend="russian-class">login
class method</link> for some reasons, just set this <link
linkend="russian-env">two environment variables</link> in the
following shell startup files:</para>
<itemizedlist>
<listitem>
<para><filename>/etc/profile</filename>:</para>
@ -204,18 +182,15 @@ MM_CHARSET=KOI8-R; export MM_CHARSET</programlisting>
setenv LANG ru_RU.KOI8-R
setenv MM_CHARSET KOI8-R</programlisting>
</listitem>
</itemizedlist>
<para>Alternatively you can add this instructions to</para>
<itemizedlist>
<itemizedlist>
<listitem>
<para><filename>/usr/share/skel/dot.profile</filename>:</para>
<para>(similar to <filename>/etc/profile</filename>
above);</para>
<para>(similar to <filename>/etc/profile</filename> above);</para>
</listitem>
<listitem>
@ -224,21 +199,18 @@ setenv MM_CHARSET KOI8-R</programlisting>
<para>(similar to <filename>/etc/csh.login</filename>
above).</para>
</listitem>
</itemizedlist>
</sect3>
</sect2>
<sect2 id="russian-printer">
<title>Printer Setup</title>
<para>Since most printers with Russian characters comes with
hardware code page CP866, special output filter needed for KOI8-R
-&gt; CP866 conversion. Such filter installed by default as
<filename>/usr/libexec/lpr/ru/koi2alt</filename>. So, Russian
printer <filename>/etc/printcap</filename> entry should looks
like:</para>
<para>Since most printers with Russian characters comes with hardware
code page CP866, special output filter needed for KOI8-R -&gt; CP866
conversion. Such filter installed by default as
<filename>/usr/libexec/lpr/ru/koi2alt</filename>. So, Russian printer
<filename>/etc/printcap</filename> entry should looks like:</para>
<programlisting>
lp|Russian local line printer:\
@ -246,22 +218,19 @@ lp|Russian local line printer:\
:lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs:</programlisting>
<para>See &man.printcap.5; for detailed description.</para>
</sect2>
<sect2 id="russian-msdosfs">
<title>MSDOS FS and Russian file names</title>
<para>Look at following example &man.fstab.5; entry to enable support for Russian
file names in MSDOS FS:</para>
<para>Look at following example &man.fstab.5; entry to enable support
for Russian file names in MSDOS FS:</para>
<programlisting>
/dev/sd0s1 /dos/c msdos rw,-W=koi2dos,-L=ru_RU.KOI8-R 0 0</programlisting>
<para>See
&man.mount.msdos.8; for detailed description of
<para>See &man.mount.msdos.8; for detailed description of
<option>-W</option> and <option>-L</option> options.</para>
</sect2>
<sect2 id="russian-xwindow">
@ -270,22 +239,18 @@ lp|Russian local line printer:\
<para>Step by step instructions:</para>
<procedure>
<step>
<para>Do
<link linkend="russian-locale">non-X locale setup</link>
<para>Do <link linkend="russian-locale">non-X locale setup</link>
first as described.</para>
<note>
<para><anchor id="russian-note">Russian KOI8-R locale may
not work with old XFree86 releases (lower than 3.3).
XFree86 port from
<filename>/usr/ports/x11/XFree86</filename> already have
most recent XFree86 version, so it will work, if you
install XFree86 from this port. XFree86 version shipped
with the latest FreeBSD distribution should work too
(check XFree86 version number not less than 3.3
first).</para>
<para><anchor id="russian-note">Russian KOI8-R locale may not work
with old XFree86 releases (lower than 3.3). XFree86 port from
<filename>/usr/ports/x11/XFree86</filename> already have most
recent XFree86 version, so it will work, if you install XFree86
from this port. XFree86 version shipped with the latest FreeBSD
distribution should work too (check XFree86 version number not
less than 3.3 first).</para>
</note>
</step>
@ -293,63 +258,61 @@ lp|Russian local line printer:\
<para>Go to <filename>/usr/ports/russian/X.language</filename>
directory and say
<screen>&prompt.root; <userinput>make all install</userinput></screen>
there. This port install latest
version of KOI8-R fonts. XFree86 3.3 already have some
KOI8-R fonts, but this ones scaled better.</para>
there. This port install latest version of KOI8-R fonts. XFree86
3.3 already have some KOI8-R fonts, but this ones scaled
better.</para>
<para>Check find <literal>"Files"</literal> section
in your <filename>/etc/XF86Config</filename>, following
lines must be before any other <literal>FontPath</literal>
entries:</para>
<para>Check find <literal>"Files"</literal> section in your
<filename>/etc/XF86Config</filename>, following lines must be
before any other <literal>FontPath</literal> entries:</para>
<programlisting>
FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/misc"
FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/75dpi"
FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/100dpi"</programlisting>
<para>If you use high resolution video mode, swap 75 dpi and
100 dpi lines.</para>
<para>If you use high resolution video mode, swap 75 dpi and 100 dpi
lines.</para>
</step>
<step>
<para>To activate Russian keyboard add
<programlisting>
XkbKeymap "xfree86(ru)"</programlisting> line into
<literal>"Keyboard"</literal> section in your
<filename>/etc/XF86Config</filename>, also make sure that
<literal>XkbDisable</literal> is turned off
(commented out) there.</para>
XkbKeymap "xfree86(ru)"</programlisting>
<para>RUS/LAT switch will be <literal>CapsLock</literal>. Old CapsLock function still
available via <literal>Shift+CapsLock</literal>
(in LAT mode only).</para>
line into <literal>"Keyboard"</literal> section in your
<filename>/etc/XF86Config</filename>, also make sure that
<literal>XkbDisable</literal> is turned off (commented out)
there.</para>
<para>RUS/LAT switch will be <literal>CapsLock</literal>. Old
CapsLock function still available via
<literal>Shift+CapsLock</literal> (in LAT mode only).</para>
<note>
<para>Russian XKB keyboard may not work with old XFree86
versions, see <link
linkend="russian-note">locale note</link> for more info.
Russian XKB keyboard may not work with non-localized
applications too, minimally localized application should
call <literal>XtSetLanguageProc
(NULL, NULL, NULL);</literal> function early in the program.</para>
<para>Russian XKB keyboard may not work with old XFree86 versions,
see <link linkend="russian-note">locale note</link> for more
info. Russian XKB keyboard may not work with non-localized
applications too, minimally localized application should call
<literal>XtSetLanguageProc (NULL, NULL, NULL);</literal>
function early in the program.</para>
</note>
</step>
</procedure>
</sect2>
</sect1>
<sect1 id="german">
<title>German Language (ISO 8859-1)</title>
<para>Slaven Rezic <email>eserte@cs.tu-berlin.de</email> wrote a tutorial how to use umlauts on a FreeBSD machine. The tutorial is written in German and available at <ulink URL="http://www.de.freebsd.org/de/umlaute/">http://www.de.freebsd.org/de/umlaute/</ulink>.</para>
<para>Slaven Rezic <email>eserte@cs.tu-berlin.de</email> wrote a tutorial
how to use umlauts on a FreeBSD machine. The tutorial is written in
German and available at <ulink
URL="http://www.de.freebsd.org/de/umlaute/">http://www.de.freebsd.org/de/umlaute/</ulink>.</para>
</sect1>
</chapter>
</chapter>
<!--
Local Variables:

760
en_US.ISO_8859-1/books/handbook/linuxemu/chapter.sgml
View file

File diff suppressed because it is too large Load diff

466
en_US.ISO_8859-1/books/handbook/mail/chapter.sgml
View file

@ -1,37 +1,34 @@
<chapter id="mail">
<chapter id="mail">
<title>Electronic Mail</title>
<para><emphasis>Contributed by &a.wlloyd;.</emphasis></para>
<para>Electronic Mail configuration is the subject of many <link
linkend="bibliography">System Administration</link> books. If you
plan on doing anything beyond setting up one mailhost for your
network, you need industrial strength help.</para>
<para>Some parts of E-Mail configuration are controlled in the Domain
Name System (DNS). If you are going to run your own own DNS server
check out <filename>/etc/namedb</filename> and <command>man -k named</command> for more information.</para>
linkend="bibliography">System Administration</link> books. If you plan
on doing anything beyond setting up one mailhost for your network, you
need industrial strength help.</para>
<para>Some parts of E-Mail configuration are controlled in the Domain Name
System (DNS). If you are going to run your own own DNS server check out
<filename>/etc/namedb</filename> and <command>man -k named</command> for
more information.</para>
<sect1>
<title>Basic Information</title>
<para>These are the major programs involved in an E-Mail exchange. A
&ldquo;mailhost&rdquo; is a server that is
responsible for delivering and receiving all email for your host,
and possibly your network.</para>
&ldquo;mailhost&rdquo; is a server that is responsible for delivering
and receiving all email for your host, and possibly your network.</para>
<sect2>
<title>User program</title>
<para>This is a program like <application >elm</application>, <application>pine</application>,
<application>mail</application>, or something more sophisticated like a WWW
browser. This program will simply pass off all e-mail
transactions to the local &ldquo;mailhost&rdquo; ,
either by calling <command>sendmail</command> or
delivering it over TCP.</para>
<para>This is a program like <application >elm</application>,
<application>pine</application>, <application>mail</application>, or
something more sophisticated like a WWW browser. This program will
simply pass off all e-mail transactions to the local
&ldquo;mailhost&rdquo; , either by calling <command>sendmail</command>
or delivering it over TCP.</para>
</sect2>
<sect2>
@ -39,150 +36,137 @@
<para>Usually this program is <command>sendmail</command> or
<command>smail</command> running in the background. Turn it off or
change the command line options in
<filename>/etc/rc.conf</filename> (or, prior to FreeBSD 2.2.2,
<filename>/etc/sysconfig</filename>). It is best to leave it on,
unless you have a specific reason to want it off. Example: You
are building a <link
change the command line options in <filename>/etc/rc.conf</filename>
(or, prior to FreeBSD 2.2.2, <filename>/etc/sysconfig</filename>). It
is best to leave it on, unless you have a specific reason to want it
off. Example: You are building a <link
linkend="firewalls">Firewall</link>.</para>
<para>You should be aware that <command>sendmail</command> is a potential weak link in a
secure site. Some versions of <command>sendmail</command> have known security
problems.</para>
<para>You should be aware that <command>sendmail</command> is a
potential weak link in a secure site. Some versions of
<command>sendmail</command> have known security problems.</para>
<para><command>sendmail</command> does two jobs. It looks after delivering
and receiving mail.</para>
<para><command>sendmail</command> does two jobs. It looks after
delivering and receiving mail.</para>
<para>If <command>sendmail</command>
needs to deliver mail off your site it will look up in
the DNS to determine the actual host that will receive mail for
the destination.</para>
<para>If it is acting as a delivery agent <command>sendmail</command> will take the message from the
local queue and deliver it across the Internet to another sendmail
on the receivers computer.</para>
<para>If <command>sendmail</command> needs to deliver mail off your site
it will look up in the DNS to determine the actual host that will
receive mail for the destination.</para>
<para>If it is acting as a delivery agent <command>sendmail</command>
will take the message from the local queue and deliver it across the
Internet to another sendmail on the receivers computer.</para>
</sect2>
<sect2>
<title>DNS &mdash; Name Service</title>
<para>The Domain Name System and its daemon <command>named</command>, contain the database mapping
hostname to IP address, and hostname to mailhost. The IP address
is specified in an A record. The MX record specifies the
mailhost that will receive mail for you. If you do not have a
MX record mail for your hostname, the mail will be delivered to
<para>The Domain Name System and its daemon <command>named</command>,
contain the database mapping hostname to IP address, and hostname to
mailhost. The IP address is specified in an A record. The MX record
specifies the mailhost that will receive mail for you. If you do not
have a MX record mail for your hostname, the mail will be delivered to
your host directly.</para>
<para>Unless you are running your own DNS server, you will not be
able to change any information in the DNS yourself. If you are
using an Internet Provider, speak to them.</para>
<para>Unless you are running your own DNS server, you will not be able
to change any information in the DNS yourself. If you are using an
Internet Provider, speak to them.</para>
</sect2>
<sect2>
<title>POP Servers</title>
<para>This program gets the mail from your mailbox and gives it to
your browser. If you want to run a POP server on your computer,
you will need to do 2 things.</para>
<para>This program gets the mail from your mailbox and gives it to your
browser. If you want to run a POP server on your computer, you will
need to do 2 things.</para>
<procedure>
<step>
<para>Get pop software from the <ulink
URL="../ports/mail.html">Ports collection</ulink> that
can be found in <filename>/usr/ports</filename> or packages
collection. This handbook section has a complete reference
on the <link linkend="ports">Ports</link> system.</para>
URL="../ports/mail.html">Ports collection</ulink> that can be
found in <filename>/usr/ports</filename> or packages collection.
This handbook section has a complete reference on the <link
linkend="ports">Ports</link> system.</para>
</step>
<step>
<para>Modify <filename>/etc/inetd.conf</filename>
to load the POP server.</para>
<para>Modify <filename>/etc/inetd.conf</filename> to load the POP
server.</para>
</step>
</procedure>
<para>The pop program will have instructions with it. Read
them.</para>
<para>The pop program will have instructions with it. Read them.</para>
</sect2>
</sect1>
<sect1>
<title>Configuration</title>
<sect2>
<title>Basic</title>
<para>As your FreeBSD system comes &ldquo;out of the box&rdquo;[TM], you should
be able to send E-mail to external hosts as long as you have
<para>As your FreeBSD system comes &ldquo;out of the box&rdquo;[TM], you
should be able to send E-mail to external hosts as long as you have
<filename>/etc/resolv.conf</filename> setup or are running a name
server. If you want to have mail for your host delivered to your
specific host,there are two methods:</para>
<itemizedlist>
<listitem>
<para>Run a name server (<command>man -k named</command>) and have your own domain
<hostid role="domainname">smallminingco.com </hostid></para>
<para>Run a name server (<command>man -k named</command>) and have
your own domain <hostid role="domainname">smallminingco.com
</hostid></para>
</listitem>
<listitem>
<para>Get mail delivered to the current DNS name for your host.
Ie: <hostid role="fqdn">dorm6.ahouse.school.edu </hostid></para>
<para>Get mail delivered to the current DNS name for your host. Ie:
<hostid role="fqdn">dorm6.ahouse.school.edu </hostid></para>
</listitem>
</itemizedlist>
<para>No matter what option you choose, to have mail delivered
directly to your host, you must be a full Internet host. You must
have a permanent IP address. IE: NO dynamic PPP. If you are
behind a firewall, the firewall must be passing on smtp traffic to
you. From <filename>/etc/services</filename>:</para>
<para>No matter what option you choose, to have mail delivered directly
to your host, you must be a full Internet host. You must have a
permanent IP address. IE: NO dynamic PPP. If you are behind a
firewall, the firewall must be passing on smtp traffic to you. From
<filename>/etc/services</filename>:</para>
<programlisting
>smtp 25/tcp mail #Simple Mail Transfer</programlisting>
<programlisting>
smtp 25/tcp mail #Simple Mail Transfer</programlisting>
<para>If you
want to receive mail at your host itself, you must make sure that
the DNS MX entry points to your host address, or there is no MX
entry for your DNS name.</para>
<para>If you want to receive mail at your host itself, you must make
sure that the DNS MX entry points to your host address, or there is no
MX entry for your DNS name.</para>
<para>Try this:</para>
<screen>&prompt.root; <userinput>hostname</userinput>
newbsdbox.freebsd.org
&prompt.root; <userinput>host newbsdbox.freebsd.org</userinput>
newbsdbox.freebsd.org has address 204.216.27.xx</screen>
<para>If that is all that comes out for your machine, mail directory
to <email>root@newbsdbox.freebsd.org</email>
will work no problems.</para>
<para>If that is all that comes out for your machine, mail directory to
<email>root@newbsdbox.freebsd.org</email> will work no
problems.</para>
<para>If instead, you have this:</para>
<screen>&prompt.root; <userinput>host newbsdbox.freebsd.org</userinput>
newbsdbox.FreeBSD.org has address 204.216.27.xx
newbsdbox.FreeBSD.org mail is handled (pri=10) by freefall.FreeBSD.org</screen>
<para>All mail sent to your host directly will end up on
<hostid>freefall</hostid>, under the same username.</para>
<para>All mail sent to your host
directly will end up on <hostid>freefall</hostid>, under the same username.</para>
<para>This information is setup in your domain name server. This should
be the same host that is listed as your primary nameserver in
<filename>/etc/resolv.conf</filename></para>
<para>This information is setup in your domain name server. This
should be the same host that is listed as your primary nameserver
in <filename>/etc/resolv.conf</filename></para>
<para>The DNS record that carries mail routing information is the Mail
eXchange entry. If no MX entry exists, mail will be delivered directly
to the host by way of the Address record.</para>
<para>The DNS record that carries mail routing information is the
Mail eXchange entry. If no MX entry exists, mail will be
delivered directly to the host by way of the Address
record.</para>
<para>The MX entry for <hostid role="fqdn">freefall.freebsd.org</hostid> at one time.</para>
<para>The MX entry for <hostid role="fqdn">freefall.freebsd.org</hostid>
at one time.</para>
<programlisting>
freefall MX 30 mail.crl.net
@ -193,39 +177,38 @@ freefall MX 20 who.cdrom.com
freefall A 204.216.27.xx
freefall CNAME www.FreeBSD.org</programlisting>
<para><hostid>freefall</hostid> has many MX entries. The lowest MX number gets the
mail in the end. The others will queue mail temporarily, if
<hostid>freefall</hostid> is busy or down.</para>
<para><hostid>freefall</hostid> has many MX entries. The lowest MX
number gets the mail in the end. The others will queue mail
temporarily, if <hostid>freefall</hostid> is busy or down.</para>
<para>Alternate MX sites should have separate connections to the
Internet, to be most useful. An Internet Provider or other
friendly site can provide this service.</para>
<para><command>dig</command>, <command>nslookup</command>,
and <command>host</command> are your friends.</para>
Internet, to be most useful. An Internet Provider or other friendly
site can provide this service.</para>
<para><command>dig</command>, <command>nslookup</command>, and
<command>host</command> are your friends.</para>
</sect2>
<sect2 id="mail-domain">
<title>Mail for your Domain (Network).</title>
<para>To setup up a network mailhost, you need to direct the mail
from arriving at all the workstations. In other words, you want to
hijack all mail for <hostid role="domainname">*.smallminingco.com
</hostid> and divert it to one machine, your &ldquo;mailhost&rdquo;.</para>
<para>To setup up a network mailhost, you need to direct the mail from
arriving at all the workstations. In other words, you want to hijack
all mail for <hostid role="domainname">*.smallminingco.com </hostid>
and divert it to one machine, your &ldquo;mailhost&rdquo;.</para>
<para>The network users on their workstations will most likely pick
up their mail over POP or telnet.</para>
<para>The network users on their workstations will most likely pick up
their mail over POP or telnet.</para>
<para>A user account with the <emphasis>same username</emphasis> should exist on both
machines. Please use <command>adduser</command> to do
<para>A user account with the <emphasis>same username</emphasis> should
exist on both machines. Please use <command>adduser</command> to do
this as required. If you set the <literal>shell</literal> to
<literal>/nonexistent</literal>
the user will not be allowed to login.</para>
<literal>/nonexistent</literal> the user will not be allowed to
login.</para>
<para>The mailhost that you will be using must be designated the
Mail eXchange for each workstation. This must be arranged in DNS
(ie BIND, named). Please refer to a Networking book for in-depth
Mail eXchange for each workstation. This must be arranged in DNS (ie
BIND, named). Please refer to a Networking book for in-depth
information.</para>
<para>You basically need to add these lines in your DNS server.</para>
@ -234,44 +217,45 @@ freefall CNAME www.FreeBSD.org</programlisting>
pc24.smallminingco.com A <replaceable>xxx.xxx.xxx.xxx</replaceable> ; Workstation ip
MX 10 smtp.smallminingco.com ; Your mailhost</programlisting>
<para>You cannot do this yourself unless you are running a DNS
server. If you do not want to run a DNS server, get somebody else
like your Internet Provider to do it.</para>
<para>You cannot do this yourself unless you are running a DNS server.
If you do not want to run a DNS server, get somebody else like your
Internet Provider to do it.</para>
<para>This will redirect mail for the workstation to the Mail
eXchange host. It does not matter what machine the A record
points to, the mail will be sent to the MX host.</para>
<para>This will redirect mail for the workstation to the Mail eXchange
host. It does not matter what machine the A record points to, the mail
will be sent to the MX host.</para>
<para>This feature is used to implement Virtual E-Mail Hosting.</para>
<para>Example</para>
<para>I have a customer with domain foo.bar and I want all mail for
foo.bar to be sent to my machine smtp.smalliap.com. You must make
an entry in your DNS server like:</para>
foo.bar to be sent to my machine smtp.smalliap.com. You must make an
entry in your DNS server like:</para>
<programlisting>
foo.bar MX 10 smtp.smalliap.com ; your mailhost</programlisting>
<para>The A record is not needed if you only
want E-Mail for the domain. IE: Don't expect <command>ping foo.bar</command>
to work unless an Address record for <filename>foo.bar</filename>
exists as well.</para>
<para>The A record is not needed if you only want E-Mail for the domain.
IE: Don't expect <command>ping foo.bar</command> to work unless an
Address record for <filename>foo.bar</filename> exists as well.</para>
<para>On the mailhost that actually accepts mail for final delivery
to a mailbox, <command>sendmail</command> must be told what hosts it will be
accepting mail for.</para>
<para>On the mailhost that actually accepts mail for final delivery to a
mailbox, <command>sendmail</command> must be told what hosts it will
be accepting mail for.</para>
<para>Add <literal>pc24.smallminingco.com</literal> to <filename>/etc/sendmail.cw</filename> (if you are
using <literal>FEATURE(use_cw_file)</literal>), or add a <literal>Cw myhost.smalliap.com</literal>
line to <filename>/etc/sendmail.cf</filename></para>
<para>If you plan on doing anything serious with <command>sendmail</command> you should install the <command>sendmail</command>
source. The source has plenty of documentation with it. You will
find information on getting <command>sendmail</command>
source from <link linkend="sendmailuucp">the UUCP
information</link>.</para>
<para>Add <literal>pc24.smallminingco.com</literal> to
<filename>/etc/sendmail.cw</filename> (if you are using
<literal>FEATURE(use_cw_file)</literal>), or add a <literal>Cw
myhost.smalliap.com</literal> line to
<filename>/etc/sendmail.cf</filename></para>
<para>If you plan on doing anything serious with
<command>sendmail</command> you should install the
<command>sendmail</command> source. The source has plenty of
documentation with it. You will find information on getting
<command>sendmail</command> source from <link
linkend="sendmailuucp">the UUCP information</link>.</para>
</sect2>
<sect2 id="sendmailuucp">
@ -279,65 +263,56 @@ foo.bar MX 10 smtp.smalliap.com ; your mailhost</programlistin
<para><emphasis>Stolen from the FAQ.</emphasis></para>
<para>The sendmail configuration that ships with FreeBSD is suited
for sites that connect directly to the Internet. Sites that wish
to exchange their mail via UUCP must install another <command>sendmail</command>
configuration file.</para>
<para>The sendmail configuration that ships with FreeBSD is suited for
sites that connect directly to the Internet. Sites that wish to
exchange their mail via UUCP must install another
<command>sendmail</command> configuration file.</para>
<para>Tweaking <filename>/etc/sendmail.cf</filename> manually is
considered something for purists. Sendmail version 8 comes with a
new approach of generating config files via some <command>m4</command> preprocessing, where the actual
hand-crafted configuration is on a higher abstraction level. You
should use the configuration files under
considered something for purists. Sendmail version 8 comes with a new
approach of generating config files via some <command>m4</command>
preprocessing, where the actual hand-crafted configuration is on a
higher abstraction level. You should use the configuration files under
<filename>/usr/src/usr.sbin/sendmail/cf</filename>.</para>
<para>If you did not install your system with full sources, the
<command>sendmail</command> config stuff has been broken out into a separate source
distribution tarball just for you. Assuming you have your CD-ROM
mounted, do:</para>
<command>sendmail</command> config stuff has been broken out into a
separate source distribution tarball just for you. Assuming you have
your CD-ROM mounted, do:</para>
<screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>tar -xvzf /cdrom/dists/src/ssmailcf.aa</userinput></screen>
<para>Do not panic, this is only a few hundred kilobytes in size.
The file <filename>README</filename> in the <filename>cf</filename> directory can serve as a basic
introduction to m4 configuration.</para>
<para>Do not panic, this is only a few hundred kilobytes in size. The
file <filename>README</filename> in the <filename>cf</filename>
directory can serve as a basic introduction to m4
configuration.</para>
<para>For UUCP delivery, you are best advised to use the
<emphasis>mailertable</emphasis> feature. This constitutes a
database that <command>sendmail</command> can use to base its routing decision
<emphasis>mailertable</emphasis> feature. This constitutes a database
that <command>sendmail</command> can use to base its routing decision
upon.</para>
<para>First, you have to create your <filename>.mc</filename> file.
The directory
<filename>/usr/src/usr.sbin/sendmail/cf/cf</filename> is the home
of these files. Look around, there are already a few examples.
Assuming you have named your file <filename>foo.mc</filename>, all
you need to do in order to convert it into a valid
<para>First, you have to create your <filename>.mc</filename> file. The
directory <filename>/usr/src/usr.sbin/sendmail/cf/cf</filename> is the
home of these files. Look around, there are already a few examples.
Assuming you have named your file <filename>foo.mc</filename>, all you
need to do in order to convert it into a valid
<filename>sendmail.cf</filename> is:</para>
<screen>&prompt.root; <userinput>cd /usr/src/usr.sbin/sendmail/cf/cf</userinput>
&prompt.root; <userinput>make foo.cf</userinput></screen>
<para>If you don't have a <filename>/usr/obj</filename> hiearchy,
then:</para>
<screen>&prompt.root; <userinput>cp foo.cf /etc/sendmail.cf</userinput></screen>
<para>Otherwise:</para>
<screen>&prompt.root; <userinput>cp /usr/obj/`pwd`/foo.cf /etc/sendmail.cf</userinput></screen>
<para>A typical <filename>.mc</filename> file might look
like:</para>
<para>A typical <filename>.mc</filename> file might look like:</para>
<programlisting>
include(`../m4/cf.m4')
@ -358,13 +333,12 @@ MAILER(uucp)
Cw <replaceable>your.alias.host.name</replaceable>
Cw <replaceable>youruucpnodename.UUCP</replaceable></programlisting>
<para>The <literal>nodns</literal> and
<literal>nocanonify</literal> features will prevent any usage of
the DNS during mail delivery. The <literal>UUCP_RELAY</literal>
clause is needed for bizarre reasons, do not ask. Simply put an
Internet hostname there that is able to handle .UUCP pseudo-domain
addresses; most likely, you will enter the mail relay of your ISP
there.</para>
<para>The <literal>nodns</literal> and <literal>nocanonify</literal>
features will prevent any usage of the DNS during mail delivery. The
<literal>UUCP_RELAY</literal> clause is needed for bizarre reasons, do
not ask. Simply put an Internet hostname there that is able to handle
.UUCP pseudo-domain addresses; most likely, you will enter the mail
relay of your ISP there.</para>
<para>Once you have this, you need this file called
<filename>/etc/mailertable</filename>. A typical example of this
@ -381,36 +355,35 @@ interface-business.de uucp-dom:if-bus
uucp-dom:horus if-bus.UUCP
uucp-dom:if-bus . uucp-dom:sax</programlisting>
<para>As you can see, this is part of a real-life file. The first
three lines handle special cases where domain-addressed mail
should not be sent out to the default route, but instead to some
UUCP neighbor in order to &ldquo;shortcut&rdquo; the delivery path. The
next line handles mail to the local Ethernet domain that can be
delivered using SMTP. Finally, the UUCP neighbors are mentioned
in the .UUCP pseudo-domain notation, to allow for a
<literal>uucp-neighbor!recipient</literal> override of the default rules. The
last line is always a single dot, matching everything else, with
UUCP delivery to a UUCP neighbor that serves as your universal
<para>As you can see, this is part of a real-life file. The first three
lines handle special cases where domain-addressed mail should not be
sent out to the default route, but instead to some UUCP neighbor in
order to &ldquo;shortcut&rdquo; the delivery path. The next line
handles mail to the local Ethernet domain that can be delivered using
SMTP. Finally, the UUCP neighbors are mentioned in the .UUCP
pseudo-domain notation, to allow for a
<literal>uucp-neighbor!recipient</literal> override of the default
rules. The last line is always a single dot, matching everything else,
with UUCP delivery to a UUCP neighbor that serves as your universal
mail gateway to the world. All of the node names behind the
<literal>uucp-dom:</literal> keyword must be valid UUCP
neighbors, as you can verify using the command <command>uuname</command>.</para>
<literal>uucp-dom:</literal> keyword must be valid UUCP neighbors, as
you can verify using the command <command>uuname</command>.</para>
<para>As a reminder that this file needs to be converted into a DBM
database file before being usable, the command line to accomplish
this is best placed as a comment at the top of the <filename>mailertable</filename>.
You always have to execute this command each time you change your
database file before being usable, the command line to accomplish this
is best placed as a comment at the top of the
<filename>mailertable</filename>. You always have to execute this
command each time you change your
<filename>mailertable</filename>.</para>
<para>Final hint: if you are uncertain whether some particular mail
routing would work, remember the <option>-bt</option> option to
<command>sendmail</command>. It starts <command>sendmail</command>
in &ldquo;address test
mode&rdquo;; simply enter <literal>0</literal>, followed by the address
you wish to test for the mail routing. The last line tells you
the used internal mail agent, the destination host this agent will
be called with, and the (possibly translated) address. Leave this
mode by typing Control-D.</para>
<command>sendmail</command>. It starts <command>sendmail</command> in
&ldquo;address test mode&rdquo;; simply enter <literal>0</literal>,
followed by the address you wish to test for the mail routing. The
last line tells you the used internal mail agent, the destination host
this agent will be called with, and the (possibly translated) address.
Leave this mode by typing Control-D.</para>
<screen>&prompt.user; <userinput>sendmail -bt</userinput>
ADDRESS TEST MODE (ruleset 3 NOT automatically invoked)
@ -419,8 +392,6 @@ Enter &lt;ruleset&gt; &lt;address&gt;
rewrite: ruleset 0 input: foo @ interface-business . de
&hellip;
rewrite: ruleset 0 returns: $# uucp-dom $@ if-bus $: foo &lt; @ interface-business . de</screen>
</sect2>
</sect1>
@ -429,30 +400,31 @@ rewrite: ruleset 0 returns: $# uucp-dom $@ if-bus $: foo &lt; @ interface-busin
<para><emphasis>Migration from FAQ.</emphasis></para>
<sect2>
<title>Why do I have to use the FQDN for hosts on my site?</title>
<para>You will probably find that the host is actually in a
different domain; for example, if you are in <hostid role="fqdn">foo.bar.edu</hostid> and you
wish to reach a host called <hostid>mumble</hostid> in the <hostid
role="domainname">bar.edu</hostid> domain, you
will have to refer to it by the fully-qualified domain name,
<hostid role="fqdn">mumble.bar.edu</hostid>, instead of just <hostid>mumble</hostid>.</para>
<para>You will probably find that the host is actually in a different
domain; for example, if you are in <hostid
role="fqdn">foo.bar.edu</hostid> and you wish to reach a host called
<hostid>mumble</hostid> in the <hostid
role="domainname">bar.edu</hostid> domain, you will have to refer to
it by the fully-qualified domain name, <hostid
role="fqdn">mumble.bar.edu</hostid>, instead of just
<hostid>mumble</hostid>.</para>
<para>Traditionally, this was allowed by BSD BIND resolvers. However
the current version of <application>BIND</application> that ships with
<para>Traditionally, this was allowed by BSD BIND resolvers. However the
current version of <application>BIND</application> that ships with
FreeBSD no longer provides default abbreviations for non-fully
qualified domain names other than the domain you are in. So an
unqualified host <hostid>mumble</hostid> must either
be found as <hostid role="fqdn">mumble.foo.bar.edu</hostid>, or
it will be searched for in the root domain.</para>
unqualified host <hostid>mumble</hostid> must either be found as
<hostid role="fqdn">mumble.foo.bar.edu</hostid>, or it will be
searched for in the root domain.</para>
<para>This is different from the previous behavior, where the search
continued across <hostid role="domainname">mumble.bar.edu</hostid>,
and <hostid role="domainname">mumble.edu</hostid>. Have a look at
RFC 1535 for why this was considered bad practice, or even a
security hole.</para>
and <hostid role="domainname">mumble.edu</hostid>. Have a look at RFC
1535 for why this was considered bad practice, or even a security
hole.</para>
<para>As a good workaround, you can place the line
@ -464,15 +436,14 @@ search foo.bar.edu bar.edu</programlisting>
<programlisting>
domain foo.bar.edu</programlisting>
into your <filename>/etc/resolv.conf</filename>. However,
make sure that the search order does not go beyond the &ldquo;boundary
between local and public administration&rdquo;, as RFC 1535 calls
it.</para>
into your <filename>/etc/resolv.conf</filename>. However, make sure
that the search order does not go beyond the &ldquo;boundary between
local and public administration&rdquo;, as RFC 1535 calls it.</para>
</sect2>
<sect2>
<title>Sendmail says <errorname>mail loops back to myself</errorname></title>
<title>Sendmail says <errorname>mail loops back to
myself</errorname></title>
<para>This is answered in the sendmail FAQ as follows:</para>
@ -495,41 +466,41 @@ to /etc/sendmail.cf.</programlisting>
<filename>/usr/src/usr.sbin/sendmail</filename> and is recommended
reading if you want to do any &ldquo;tweaking&rdquo; of your mail
setup.</para>
</sect2>
<sect2>
<title>How can I do E-Mail with a dialup PPP host?</title>
<para>You want to connect a FreeBSD box on a lan, to the Internet.
The FreeBSD box will be a mail gateway for the lan. The PPP
connection is non-dedicated.</para>
<para>You want to connect a FreeBSD box on a lan, to the Internet. The
FreeBSD box will be a mail gateway for the lan. The PPP connection is
non-dedicated.</para>
<para>There are at least two way to do this.</para>
<para>The other is to use UUCP.</para>
<para>The key is to get a Internet site to provide secondary MX
services for your domain. For example:</para>
<para>The key is to get a Internet site to provide secondary MX services
for your domain. For example:</para>
<programlisting>
bigco.com. MX 10 bigco.com.
MX 20 smalliap.com.</programlisting>
<para>Only one host should be specified as the final recipient ( add
<literal>Cw bigco.com</literal> in <filename>/etc/sendmail.cf</filename> on
bigco.com).</para>
<literal>Cw bigco.com</literal> in
<filename>/etc/sendmail.cf</filename> on bigco.com).</para>
<para>When the senders <command>sendmail</command> is trying to deliver the mail it
will try to connect to you over the modem link. It will most
likely time out because you are not online. <command>sendmail</command> will
automatically deliver it to the secondary MX site, ie your
Internet provider. The secondary MX site will try every
(<literal>sendmail_flags = "-bd -q15m"</literal> in
<filename>/etc/rc.conf</filename> ) 15 minutes to connect to your
host to deliver the mail to the primary MX site.</para>
<para>When the senders <command>sendmail</command> is trying to deliver
the mail it will try to connect to you over the modem link. It will
most likely time out because you are not online.
<command>sendmail</command> will automatically deliver it to the
secondary MX site, ie your Internet provider. The secondary MX site
will try every (<literal>sendmail_flags = "-bd -q15m"</literal> in
<filename>/etc/rc.conf</filename> ) 15 minutes to connect to your host
to deliver the mail to the primary MX site.</para>
<para>You might want to use something like this as a login script.</para>
<para>You might want to use something like this as a login
script.</para>
<programlisting>
#!/bin/sh
@ -537,11 +508,10 @@ bigco.com. MX 10 bigco.com.
( sleep 60 ; /usr/sbin/sendmail -q ) &amp;
/usr/sbin/ppp -direct pppbigco</programlisting>
<para>If you are going to create a separate
login script for a user you could use <command>sendmail
-qRbigco.com</command> instead in the script above. This will
force all mail in your queue for bigco.com to be processed
immediately.</para>
<para>If you are going to create a separate login script for a user you
could use <command>sendmail -qRbigco.com</command> instead in the
script above. This will force all mail in your queue for bigco.com to
be processed immediately.</para>
<para>A further refinement of the situation is as follows.</para>
@ -574,11 +544,9 @@ the customer connection. You then send to your customer. Only works for
"hosts", so you need to get your customer to name their mail machine
"customer.com" as well as "hostname.customer.com" in the DNS. Just put
an A record in the DNS for "customer.com".</programlisting>
</sect2>
</sect1>
</chapter>
</chapter>
<!--
Local Variables:

636
en_US.ISO_8859-1/books/handbook/mirrors/chapter.sgml
View file

File diff suppressed because it is too large Load diff

18
en_US.ISO_8859-1/books/handbook/pgpkeys/chapter.sgml
View file

@ -1,17 +1,16 @@
<chapter id="pgpkeys">
<chapter id="pgpkeys">
<title>PGP keys</title>
<para>In case you need to verify a signature or send encrypted email to
one of the officers or core team members a number of keys are
provided here for your convenience.</para>
<para>In case you need to verify a signature or send encrypted email to one
of the officers or core team members a number of keys are provided here
for your convenience.</para>
<sect1>
<title>Officers</title>
<sect2>
<title>FreeBSD Security Officer <email>security-officer@freebsd.org</email></title>
<title>FreeBSD Security Officer
<email>security-officer@freebsd.org</email></title>
<programlisting>
FreeBSD Security Officer &lt;security-officer@freebsd.org&gt;
@ -43,7 +42,6 @@ v4Xhp6a8RtDdUMBOTtro16iulGiRrCKxzVgEl4i+9Z0ZiE6BWlg5AetoF5n3mGk1
lw==
=ipyA
-----END PGP PUBLIC KEY BLOCK-----</programlisting>
</sect2>
<sect2>
@ -74,14 +72,12 @@ RzUrblyF84tJyA7Rr1p+A7dxf7je3Zx5QMEXosWL1WGnS5vC9YH2WZwv6sCU61gU
rSy9z8KHlBEHh+Z6fdRMrjd9byPf+n3cktT0NhS23oXB1ZhNZcB2KKhVPlNctMqO
3gTYx+Nlo6xqjR+J2NnBYU8p =7fQV
-----END PGP PUBLIC KEY BLOCK-----</programlisting>
</sect2>
</sect1>
<sect1>
<title>Core Team members</title>
<sect2>
<title>&a.asami;</title>
@ -564,7 +560,7 @@ xDZaEUQEbWqxfiwuzizAjkaxrW7dBbWILwWqrYF5TXClw+oUU/oIUW4t6t+GpAO1
-----END PGP PUBLIC KEY BLOCK-----</programlisting>
</sect2>
</sect1>
</chapter>
</chapter>
<!--
Local Variables:

271
en_US.ISO_8859-1/books/handbook/policies/chapter.sgml
View file

@ -1,11 +1,10 @@
<chapter id="policies">
<chapter id="policies">
<title>Source Tree Guidelines and Policies</title>
<para><emphasis>Contributed by &a.phk;.</emphasis></para>
<para>This chapter documents various guidelines and policies in force
for the FreeBSD source tree.</para>
<para>This chapter documents various guidelines and policies in force for
the FreeBSD source tree.</para>
<sect1 id="policies-maintainer">
<title><makevar>MAINTAINER</makevar> on Makefiles</title>
@ -13,36 +12,33 @@
<para>June 1996.</para>
<para>If a particular portion of the FreeBSD distribution is being
maintained by a person or group of persons, they can communicate
this fact to the world by adding a
maintained by a person or group of persons, they can communicate this
fact to the world by adding a
<programlisting>
MAINTAINER= email-addresses</programlisting>
line to the <filename>Makefile</filename>s covering this portion
of the source tree.</para>
line to the <filename>Makefile</filename>s covering this portion of the
source tree.</para>
<para>The semantics of this are as follows:</para>
<para>The maintainer owns and is responsible for that code. This
means that he is responsible for fixing bugs and answer problem
reports pertaining to that piece of the code, and in the case of
contributed software, for tracking new versions, as
appropriate.</para>
<para>The maintainer owns and is responsible for that code. This means
that he is responsible for fixing bugs and answer problem reports
pertaining to that piece of the code, and in the case of contributed
software, for tracking new versions, as appropriate.</para>
<para>Changes to directories which have a maintainer defined shall be
sent to the maintainer for review before being committed. Only if
the maintainer does not respond for an unacceptable period of time,
to several emails, will it be acceptable to commit changes without
review by the maintainer. However, it is suggested that you try and
have the changes reviewed by someone else if at all
possible.</para>
<para>Changes to directories which have a maintainer defined shall be sent
to the maintainer for review before being committed. Only if the
maintainer does not respond for an unacceptable period of time, to
several emails, will it be acceptable to commit changes without review
by the maintainer. However, it is suggested that you try and have the
changes reviewed by someone else if at all possible.</para>
<para>It is of course not acceptable to add a person or group as
maintainer unless they agree to assume this duty. On the other hand
it doesn't have to be a committer and it can easily be a group of
maintainer unless they agree to assume this duty. On the other hand it
doesn't have to be a committer and it can easily be a group of
people.</para>
</sect1>
<sect1>
@ -52,31 +48,31 @@ MAINTAINER= email-addresses</programlisting>
<para>June 1996.</para>
<para>Some parts of the FreeBSD distribution consist of software that
is actively being maintained outside the FreeBSD project. For
historical reasons, we call this <emphasis>contributed</emphasis>
software. Some examples are perl, gcc and patch.</para>
<para>Some parts of the FreeBSD distribution consist of software that is
actively being maintained outside the FreeBSD project. For historical
reasons, we call this <emphasis>contributed</emphasis> software. Some
examples are perl, gcc and patch.</para>
<para>Over the last couple of years, various methods have been used in
dealing with this type of software and all have some number of
advantages and drawbacks. No clear winner has emerged.</para>
<para>Since this is the case, after some debate one of these methods
has been selected as the &ldquo;official&rdquo; method and will be required for
future imports of software of this kind. Furthermore, it is
strongly suggested that existing contributed software converge on
this model over time, as it has significant advantages over the old
method, including the ability to easily obtain diffs relative to the
&ldquo;official&rdquo; versions of the source by everyone (even without cvs
access). This will make it significantly easier to return changes
<para>Since this is the case, after some debate one of these methods has
been selected as the &ldquo;official&rdquo; method and will be required
for future imports of software of this kind. Furthermore, it is
strongly suggested that existing contributed software converge on this
model over time, as it has significant advantages over the old method,
including the ability to easily obtain diffs relative to the
&ldquo;official&rdquo; versions of the source by everyone (even without
cvs access). This will make it significantly easier to return changes
to the primary developers of the contributed software.</para>
<para>Ultimately, however, it comes down to the people actually doing
the work. If using this model is particularly unsuited to the
package being dealt with, exceptions to these rules may be granted
only with the approval of the core team and with the general
consensus of the other developers. The ability to maintain the
package in the future will be a key issue in the decisions.</para>
<para>Ultimately, however, it comes down to the people actually doing the
work. If using this model is particularly unsuited to the package being
dealt with, exceptions to these rules may be granted only with the
approval of the core team and with the general consensus of the other
developers. The ability to maintain the package in the future will be a
key issue in the decisions.</para>
<note>
<para>Because of some unfortunate design limitations with the RCS file
@ -93,76 +89,72 @@ MAINTAINER= email-addresses</programlisting>
language will be used as example of how this model works:</para>
<para><filename>src/contrib/tcl</filename> contains the source as
distributed by the maintainers of this package. Parts that are
entirely not applicable for FreeBSD can be removed. In the case of
Tcl, the <filename>mac</filename>, <filename>win</filename> and
<filename>compat</filename> subdirectories were eliminated before
the import</para>
distributed by the maintainers of this package. Parts that are entirely
not applicable for FreeBSD can be removed. In the case of Tcl, the
<filename>mac</filename>, <filename>win</filename> and
<filename>compat</filename> subdirectories were eliminated before the
import</para>
<para><filename>src/lib/libtcl</filename> contains only a "bmake style"
<filename>Makefile</filename> that uses the standard
<filename>bsd.lib.mk</filename> makefile rules to produce the
library and install the documentation.</para>
<filename>bsd.lib.mk</filename> makefile rules to produce the library
and install the documentation.</para>
<para><filename>src/usr.bin/tclsh</filename> contains only a bmake style
<filename>Makefile</filename> which will produce and install the
<command>tclsh</command> program and its associated man-pages using the standard
<filename>bsd.prog.mk</filename> rules.</para>
<command>tclsh</command> program and its associated man-pages using the
standard <filename>bsd.prog.mk</filename> rules.</para>
<para><filename>src/tools/tools/tcl_bmake</filename> contains a couple of
shell-scripts that can be of help when the tcl software needs
updating. These are not part of the built or installed
software.</para>
shell-scripts that can be of help when the tcl software needs updating.
These are not part of the built or installed software.</para>
<para>The important thing here is that the
<filename>src/contrib/tcl</filename> directory is created according
to the rules: It is supposed to contain the sources as distributed
(on a proper CVS vendor-branch and without RCS keyword expansion) with as few FreeBSD-specific changes
as possible. The 'easy-import' tool on freefall will assist in
doing the import, but if there are any doubts on how to go about it,
it is imperative that you ask first and not blunder ahead and hope
it &ldquo;works out&rdquo;. CVS is not forgiving of import accidents and a fair
amount of effort is required to back out major mistakes.</para>
<filename>src/contrib/tcl</filename> directory is created according to
the rules: It is supposed to contain the sources as distributed (on a
proper CVS vendor-branch and without RCS keyword expansion) with as few
FreeBSD-specific changes as possible. The 'easy-import' tool on
freefall will assist in doing the import, but if there are any doubts on
how to go about it, it is imperative that you ask first and not blunder
ahead and hope it &ldquo;works out&rdquo;. CVS is not forgiving of
import accidents and a fair amount of effort is required to back out
major mistakes.</para>
<para>Because of the previously mentioned design limitations with CVS's vendor
branches, it is required that &ldquo;official&rdquo; patches from the vendor be
applied to the original distributed sources and the result
re-imported onto the vendor branch again. Official patches should
never be patched into the FreeBSD checked out version and
"committed", as this destroys the vendor branch coherency and makes
importing future versions rather difficult as there will be
conflicts.</para>
<para>Because of the previously mentioned design limitations with CVS's
vendor branches, it is required that &ldquo;official&rdquo; patches from
the vendor be applied to the original distributed sources and the result
re-imported onto the vendor branch again. Official patches should never
be patched into the FreeBSD checked out version and "committed", as this
destroys the vendor branch coherency and makes importing future versions
rather difficult as there will be conflicts.</para>
<para>Since many packages contain files that are meant for
compatibility with other architectures and environments that
FreeBSD, it is permissible to remove parts of the distribution tree
that are of no interest to FreeBSD in order to save space. Files
containing copyright notices and release-note kind of information
applicable to the remaining files shall <emphasis>not</emphasis> be
removed.</para>
<para>Since many packages contain files that are meant for compatibility
with other architectures and environments that FreeBSD, it is
permissible to remove parts of the distribution tree that are of no
interest to FreeBSD in order to save space. Files containing copyright
notices and release-note kind of information applicable to the remaining
files shall <emphasis>not</emphasis> be removed.</para>
<para>If it seems easier, the <command>bmake</command> <filename>Makefile</filename>s
can be produced from the dist tree automatically by some utility,
something which would hopefully make it even easier to upgrade to a
new version. If this is done, be sure to check in such utilities
(as necessary) in the <filename>src/tools</filename> directory along
with the port itself so that it is available to future
maintainers.</para>
<para>In the <filename>src/contrib/tcl</filename> level directory, a
file called <filename>FREEBSD-upgrade</filename> should be added and
it should states things like:</para>
<para>If it seems easier, the <command>bmake</command>
<filename>Makefile</filename>s can be produced from the dist tree
automatically by some utility, something which would hopefully make it
even easier to upgrade to a new version. If this is done, be sure to
check in such utilities (as necessary) in the
<filename>src/tools</filename> directory along with the port itself so
that it is available to future maintainers.</para>
<para>In the <filename>src/contrib/tcl</filename> level directory, a file
called <filename>FREEBSD-upgrade</filename> should be added and it
should states things like:</para>
<itemizedlist>
<listitem>
<para>Which files have been left out</para>
</listitem>
<listitem>
<para>Where the original distribution was obtained from and/or
the official master site.</para>
<para>Where the original distribution was obtained from and/or the
official master site.</para>
</listitem>
<listitem>
@ -170,18 +162,15 @@ MAINTAINER= email-addresses</programlisting>
</listitem>
<listitem>
<para>Perhaps an overview of the FreeBSD-specific changes that
have been made.</para>
<para>Perhaps an overview of the FreeBSD-specific changes that have
been made.</para>
</listitem>
</itemizedlist>
<para>However, please do not import
<filename>FREEBSD-upgrade</filename> with the contributed source.
Rather you should <command>cvs add FREEBSD-upgrade ; cvs ci</command> after the
initial import. Example wording from
<filename>src/contrib/cpio</filename> is below:</para>
<para>However, please do not import <filename>FREEBSD-upgrade</filename>
with the contributed source. Rather you should <command>cvs add
FREEBSD-upgrade ; cvs ci</command> after the initial import. Example
wording from <filename>src/contrib/cpio</filename> is below:</para>
<programlisting>
This directory contains virgin sources of the original distribution files
@ -222,78 +211,74 @@ All local changes should be submitted to "cpio@gnu.ai.mit.edu" for
inclusion in the next vendor release.
obrien@freebsd.org - 30 March 1997</programlisting>
</sect1>
<sect1 id="policies-shlib">
<title>Shared Libraries</title>
<para><emphasis>Contributed by &a.asami;, &a.peter;, and
&a.obrien;.<!-- <br> --> 9 December 1996.</emphasis></para>
<para><emphasis>Contributed by &a.asami;, &a.peter;, and &a.obrien;.<!--
<br> --> 9 December 1996.</emphasis></para>
<para>If you are adding shared library support to a port or other
piece of software that doesn't have one, the version numbers should
follow these rules. Generally, the resulting numbers will have
nothing to do with the release version of the software.</para>
<para>If you are adding shared library support to a port or other piece of
software that doesn't have one, the version numbers should follow these
rules. Generally, the resulting numbers will have nothing to do with
the release version of the software.</para>
<para>The three principles of shared library building are:</para>
<itemizedlist>
<listitem>
<para>Start from <literal>1.0</literal></para>
</listitem>
<listitem>
<para>If there is a change that is backwards compatible, bump
minor number</para>
</listitem>
<listitem>
<para>If there is an incompatible change, bump major
<para>If there is a change that is backwards compatible, bump minor
number</para>
</listitem>
<listitem>
<para>If there is an incompatible change, bump major number</para>
</listitem>
</itemizedlist>
<para>For instance, added functions and bugfixes result in the minor
version number being bumped, while deleted functions, changed
function call syntax etc. will force the major version number to
change.</para>
version number being bumped, while deleted functions, changed function
call syntax etc. will force the major version number to change.</para>
<para>Stick to version numbers of the form major.minor (<replaceable>x</replaceable>.<replaceable>y</replaceable>). Our
dynamic linker does not handle version numbers of the form <replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable>
well. Any version number after the <replaceable>y</replaceable> (ie. the third digit) is
totally ignored when comparing shared lib version numbers to decide
which library to link with. Given two shared libraries that differ
only in the &ldquo;micro&rdquo; revision, <command>ld.so</command> will link with the higher one.
Ie: if you link with <filename>libfoo.so.3.3.3</filename>, the
linker only records <literal>3.3</literal> in the headers, and will link with anything
starting with <replaceable>libfoo.so.3</replaceable>.<replaceable>(anything &gt;=
3)</replaceable>.<replaceable>(highest available)</replaceable>.</para>
<para>Stick to version numbers of the form major.minor
(<replaceable>x</replaceable>.<replaceable>y</replaceable>). Our
dynamic linker does not handle version numbers of the form
<replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable>
well. Any version number after the <replaceable>y</replaceable>
(ie. the third digit) is totally ignored when comparing shared lib
version numbers to decide which library to link with. Given two shared
libraries that differ only in the &ldquo;micro&rdquo; revision,
<command>ld.so</command> will link with the higher one. Ie: if you link
with <filename>libfoo.so.3.3.3</filename>, the linker only records
<literal>3.3</literal> in the headers, and will link with anything
starting with
<replaceable>libfoo.so.3</replaceable>.<replaceable>(anything &gt;=
3)</replaceable>.<replaceable>(highest
available)</replaceable>.</para>
<note>
<para><command>ld.so</command> will always use the highest
&ldquo;minor&rdquo; revision. Ie: it will use <filename>libc.so.2.2</filename>
in preference to <filename>libc.so.2.0</filename>, even if the
program was initially linked with
<filename>libc.so.2.0</filename>.</para>
&ldquo;minor&rdquo; revision. Ie: it will use
<filename>libc.so.2.2</filename> in preference to
<filename>libc.so.2.0</filename>, even if the program was initially
linked with <filename>libc.so.2.0</filename>.</para>
</note>
<para>For non-port libraries, it is also our policy to change the
shared library version number only once between releases. When you
make a change to a system library that requires the version number
to be bumped, check the <filename>Makefile</filename>'s commit logs.
It is the responsibility of the committer to ensure that the first
such change since the release will result in the shared library
version number in the <filename>Makefile</filename> to be updated,
and any subsequent changes will not.</para>
<para>For non-port libraries, it is also our policy to change the shared
library version number only once between releases. When you make a
change to a system library that requires the version number to be
bumped, check the <filename>Makefile</filename>'s commit logs. It is the
responsibility of the committer to ensure that the first such change
since the release will result in the shared library version number in
the <filename>Makefile</filename> to be updated, and any subsequent
changes will not.</para>
</sect1>
</chapter>
</chapter>
<!--
Local Variables:

3195
en_US.ISO_8859-1/books/handbook/ports/chapter.sgml
View file

File diff suppressed because it is too large Load diff

1700
en_US.ISO_8859-1/books/handbook/ppp-and-slip/chapter.sgml
View file

File diff suppressed because it is too large Load diff

4150
en_US.ISO_8859-1/books/handbook/printing/chapter.sgml
View file

File diff suppressed because it is too large Load diff

242
en_US.ISO_8859-1/books/handbook/quotas/chapter.sgml
View file

@ -1,38 +1,35 @@
<chapter id="quotas">
<chapter id="quotas">
<title>Disk Quotas</title>
<para><emphasis>Contributed by &a.mpp;.<!-- <br> -->26 February
1996</emphasis></para>
<para>Quotas are an optional feature of the operating system that allow
you to limit the amount of disk space and/or the number of files a
user, or members of a group, may allocate on a per-file system basis.
This is used most often on timesharing systems where it is desirable
to limit the amount of resources any one user or group of users may
allocate. This will prevent one user from consuming all of the
available disk space.</para>
<para>Quotas are an optional feature of the operating system that allow you
to limit the amount of disk space and/or the number of files a user, or
members of a group, may allocate on a per-file system basis. This is used
most often on timesharing systems where it is desirable to limit the
amount of resources any one user or group of users may allocate. This
will prevent one user from consuming all of the available disk
space.</para>
<sect1>
<title>Configuring Your System to Enable Disk Quotas</title>
<para>Before attempting to use disk quotas it is necessary to make
sure that quotas are configured in your kernel. This is done by
adding the following line to your kernel configuration file:</para>
<para>Before attempting to use disk quotas it is necessary to make sure
that quotas are configured in your kernel. This is done by adding the
following line to your kernel configuration file:</para>
<programlisting>
options QUOTA</programlisting>
<para>The
stock <filename>GENERIC</filename> kernel does not have this enabled
by default, so you will have to configure, build and install a
custom kernel in order to use disk quotas. Please refer to the
<link linkend="kernelconfig">Configuring the FreeBSD Kernel</link>
section for more information on kernel configuration.</para>
<para>The stock <filename>GENERIC</filename> kernel does not have this
enabled by default, so you will have to configure, build and install a
custom kernel in order to use disk quotas. Please refer to the <link
linkend="kernelconfig">Configuring the FreeBSD Kernel</link> section
for more information on kernel configuration.</para>
<para>Next you will need to enable disk quotas in
<filename>/etc/sysconfig</filename>. This is done by changing the
line:
<filename>/etc/sysconfig</filename>. This is done by changing the line:
<programlisting>
quotas=NO</programlisting>
@ -42,105 +39,98 @@ quotas=NO</programlisting>
<programlisting>
quotas=YES</programlisting></para>
<para>If you are running FreeBSD 2.2.2 or later, the configuration
file will be <filename>/etc/rc.conf</filename> instead and the
variable name changed to:</para>
<para>If you are running FreeBSD 2.2.2 or later, the configuration file
will be <filename>/etc/rc.conf</filename> instead and the variable name
changed to:</para>
<programlisting>
check_quotas=YES</programlisting>
<para>Finally you will need to edit <filename>/etc/fstab</filename> to
enable disk quotas on a per-file system basis. This is where you
can either enable user or group quotas or both for all of your file
enable disk quotas on a per-file system basis. This is where you can
either enable user or group quotas or both for all of your file
systems.</para>
<para>To enable per-user quotas on a file system, add the <literal>userquota</literal> option to the options field in the
<filename>/etc/fstab</filename> entry for the file system you want
to to enable quotas on. For example:</para>
<para>To enable per-user quotas on a file system, add the
<literal>userquota</literal> option to the options field in the
<filename>/etc/fstab</filename> entry for the file system you want to to
enable quotas on. For example:</para>
<programlisting>
/dev/sd1s2g /home ufs rw,userquota 1 2</programlisting>
<para>Similarly, to enable group quotas, use the
<literal>groupquota</literal> option instead of the <literal>userquota</literal> keyword. To enable both user and
group quotas, change the entry as follows:</para>
<literal>groupquota</literal> option instead of the
<literal>userquota</literal> keyword. To enable both user and group
quotas, change the entry as follows:</para>
<programlisting>
/dev/sd1s2g /home ufs rw,userquota,groupquota 1 2</programlisting>
<para>By default the quota files are stored in the root directory of
the file system with the names <filename>quota.user</filename> and
<filename>quota.group</filename> for user and group quotas
respectively. See <command>man fstab</command> for more
information. Even though that man page says that you can specify an
alternate location for the quota files, this is not recommended
since all of the various quota utilities do not seem to handle this
properly.</para>
<para>By default the quota files are stored in the root directory of the
file system with the names <filename>quota.user</filename> and
<filename>quota.group</filename> for user and group quotas respectively.
See <command>man fstab</command> for more information. Even though that
man page says that you can specify an alternate location for the quota
files, this is not recommended since all of the various quota utilities
do not seem to handle this properly.</para>
<para>At this point you should reboot your system with your new
kernel. <filename>/etc/rc</filename> will automatically run the
appropriate commands to create the initial quota files for all of
the quotas you enabled in <filename>/etc/fstab</filename>, so there
is no need to manually create any zero length quota files.</para>
<para>In the normal course of operations you should not be required to
run the <command>quotacheck</command>, <command>quotaon</command>, or <command>quotaoff</command> commands manually. However, you may
want to read their man pages just to be familiar with their
operation.</para>
<para>At this point you should reboot your system with your new kernel.
<filename>/etc/rc</filename> will automatically run the appropriate
commands to create the initial quota files for all of the quotas you
enabled in <filename>/etc/fstab</filename>, so there is no need to
manually create any zero length quota files.</para>
<para>In the normal course of operations you should not be required to run
the <command>quotacheck</command>, <command>quotaon</command>, or
<command>quotaoff</command> commands manually. However, you may want to
read their man pages just to be familiar with their operation.</para>
</sect1>
<sect1>
<title>Setting Quota Limits</title>
<para>Once you have configured your system to enable quotas, verify
that they really are enabled. An easy way to do this is to run</para>
<para>Once you have configured your system to enable quotas, verify that
they really are enabled. An easy way to do this is to run</para>
<screen>&prompt.root; <userinput>quota -v</userinput></screen>
<para>You should see a one line summary of
disk usage and current quota limits for each file system that quotas
are enabled on.</para>
<para>You should see a one line summary of disk usage and current quota
limits for each file system that quotas are enabled on.</para>
<para>You are now ready to start assigning quota limits with the
<command>edquota</command> command.</para>
<para>You have several options on how to enforce limits on the amount
of disk space a user or group may allocate, and how many files they
may create. You may limit allocations based on disk space (block
quotas) or number of files (inode quotas) or a combination of both.
Each of these limits are further broken down into two categories:
hard and soft limits.</para>
<para>You have several options on how to enforce limits on the amount of
disk space a user or group may allocate, and how many files they may
create. You may limit allocations based on disk space (block quotas) or
number of files (inode quotas) or a combination of both. Each of these
limits are further broken down into two categories: hard and soft
limits.</para>
<para>A hard limit may not be exceeded. Once a user reaches their
hard limit they may not make any further allocations on the file
system in question. For example, if the user has a hard limit of
500 blocks on a file system and is currently using 490 blocks, the
user can only allocate an additional 10 blocks. Attempting to
allocate an additional 11 blocks will fail.</para>
<para>A hard limit may not be exceeded. Once a user reaches their hard
limit they may not make any further allocations on the file system in
question. For example, if the user has a hard limit of 500 blocks on a
file system and is currently using 490 blocks, the user can only
allocate an additional 10 blocks. Attempting to allocate an additional
11 blocks will fail.</para>
<para>Soft limits on the other hand can be exceeded for a limited
amount of time. This period of time is known as the grace period,
which is one week by default. If a user stays over his or her soft
limit longer than their grace period, the soft limit will turn into
a hard limit and no further allocations will be allowed. When the
user drops back below the soft limit, the grace period will be
reset.</para>
<para>Soft limits on the other hand can be exceeded for a limited amount
of time. This period of time is known as the grace period, which is one
week by default. If a user stays over his or her soft limit longer than
their grace period, the soft limit will turn into a hard limit and no
further allocations will be allowed. When the user drops back below the
soft limit, the grace period will be reset.</para>
<para>The following is an example of what you might see when you run
then <command>edquota</command> command. When the
<command>edquota</command> command is invoked, you are
placed into the editor specified by the <envar>EDITOR</envar>
environment variable, or in the <command>vi</command>
editor if the <envar>EDITOR</envar> variable is not set, to
allow you to edit the quota limits.</para>
<command>edquota</command> command is invoked, you are placed into the
editor specified by the <envar>EDITOR</envar> environment variable, or
in the <command>vi</command> editor if the <envar>EDITOR</envar>
variable is not set, to allow you to edit the quota limits.</para>
<screen>&prompt.root; <userinput>edquota -u test</userinput></screen>
<programlisting>
Quotas for user test:
/usr: blocks in use: 65, limits (soft = 50, hard = 75)
@ -148,57 +138,48 @@ Quotas for user test:
/usr/var: blocks in use: 0, limits (soft = 50, hard = 75)
inodes in use: 0, limits (soft = 50, hard = 60)</programlisting>
<para>You will
normally see two lines for each file system that has quotas enabled.
One line for the block limits, and one line for inode limits.
Simply change the value you want updated to modify the quota limit.
For example, to raise this users block limit from a soft limit of 50
and a hard limit of 75 to a soft limit of 500 and a hard limit of
600, change:
<para>You will normally see two lines for each file system that has quotas
enabled. One line for the block limits, and one line for inode limits.
Simply change the value you want updated to modify the quota limit. For
example, to raise this users block limit from a soft limit of 50 and a
hard limit of 75 to a soft limit of 500 and a hard limit of 600, change:
<programlisting> /usr: blocks in use: 65, limits (soft = 50, hard =
75)</programlisting> to: <programlisting> /usr: blocks in use: 65,
limits (soft = 500, hard = 600)</programlisting></para>
<programlisting>
/usr: blocks in use: 65, limits (soft = 50, hard = 75)</programlisting> to:
<programlisting>
/usr: blocks in use: 65, limits (soft = 500, hard = 600)</programlisting></para>
<para>The new
quota limits will be in place when you exit the editor.</para>
<para>Sometimes it is desirable to set quota limits on a range of
uids. This can be done by use of the <option>-p</option> option on
the <command>edquota</command> command. First, assign
the desired quota limit to a user, and then run <command>edquota -p
protouser startuid-enduid</command>. For example, if user
<username>test</username> has the desired quota limits, the
following command can be used to duplicate those quota limits for
uids 10,000 through 19,999:</para>
<para>The new quota limits will be in place when you exit the
editor.</para>
<para>Sometimes it is desirable to set quota limits on a range of uids.
This can be done by use of the <option>-p</option> option on the
<command>edquota</command> command. First, assign the desired quota
limit to a user, and then run <command>edquota -p protouser
startuid-enduid</command>. For example, if user
<username>test</username> has the desired quota limits, the following
command can be used to duplicate those quota limits for uids 10,000
through 19,999:</para>
<screen>&prompt.root; <userinput>edquota -p test 10000-19999</userinput></screen>
<para>The ability to specify uid ranges was added to the system after
2.1 was released. If you need this feature on a 2.1 system, you
will need to obtain a newer copy of edquota.</para>
<para>The ability to specify uid ranges was added to the system after 2.1
was released. If you need this feature on a 2.1 system, you will need
to obtain a newer copy of edquota.</para>
<para>See <command>man edquota</command> for more detailed
information.</para>
</sect1>
<sect1>
<title>Checking Quota Limits and Disk Usage</title>
<para>You can use either the <command>quota</command> or
the <command>repquota</command> commands to check quota
limits and disk usage. The <command>quota</command>
command can be used to check individual user and group quotas and
disk usage. Only the super-user may examine quotas and usage for
other users, or for groups that they are not a member of. The
<command>repquota</command> command can be used to get a
summary of all quotas and disk usage for file systems with quotas
enabled.</para>
<para>You can use either the <command>quota</command> or the
<command>repquota</command> commands to check quota limits and disk
usage. The <command>quota</command> command can be used to check
individual user and group quotas and disk usage. Only the super-user
may examine quotas and usage for other users, or for groups that they
are not a member of. The <command>repquota</command> command can be
used to get a summary of all quotas and disk usage for file systems with
quotas enabled.</para>
<para>The following is some sample output from the <command>quota
-v</command> command for a user that has quota limits on two file
@ -211,27 +192,26 @@ Disk quotas for user test (uid 1002):
/usr 65* 50 75 5days 7 50 60
/usr/var 0 50 75 0 50 60</programlisting>
<para>On the <filename>/usr</filename> file system in the above example this
user is currently 15 blocks over their soft limit of 50 blocks and
has 5 days of their grace period left. Note the asterisk <literal>*</literal> which
indicates that the user is currently over their quota limit.</para>
<para>On the <filename>/usr</filename> file system in the above example
this user is currently 15 blocks over their soft limit of 50 blocks and
has 5 days of their grace period left. Note the asterisk
<literal>*</literal> which indicates that the user is currently over
their quota limit.</para>
<para>Normally file systems that the user is not using any disk space
on will not show up in the output from the <command>quota</command> command, even if they have a quota limit
assigned for that file system. The <option>-v</option> option will
display those file systems, such as the
<filename>/usr/var</filename> file system in the above
<para>Normally file systems that the user is not using any disk space on
will not show up in the output from the <command>quota</command>
command, even if they have a quota limit assigned for that file system.
The <option>-v</option> option will display those file systems, such as
the <filename>/usr/var</filename> file system in the above
example.</para>
</sect1>
<sect1>
<title>* Quotas over NFS</title>
<para>This section is still under development.</para>
</sect1>
</chapter>
</chapter>
<!--
Local Variables:

1468
en_US.ISO_8859-1/books/handbook/security/chapter.sgml
View file

File diff suppressed because it is too large Load diff

1788
en_US.ISO_8859-1/books/handbook/serialcomms/chapter.sgml
View file

File diff suppressed because it is too large Load diff

173
en_US.ISO_8859-1/books/handbook/staff/chapter.sgml
View file

@ -1,9 +1,8 @@
<chapter id="staff">
<chapter id="staff">
<title>FreeBSD Project Staff</title>
<para>The FreeBSD Project is managed and operated by the following
groups of people:</para>
<para>The FreeBSD Project is managed and operated by the following groups of
people:</para>
<sect1 id="staff-core">
<title>The FreeBSD Core Team</title>
@ -15,9 +14,7 @@
<para>(in alphabetical order by last name):</para>
<itemizedlist>
<listitem>
<para>&a.asami;</para>
</listitem>
@ -77,19 +74,15 @@
<listitem>
<para>&a.joerg;</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="staff-committers">
<title>The FreeBSD Developers</title>
<para>These are the people who have commit privileges and do the
engineering work on the FreeBSD source tree. All core team members
are also developers.</para>
engineering work on the FreeBSD source tree. All core team members are
also developers.</para>
<itemizedlist>
<listitem>
@ -579,52 +572,49 @@
<listitem>
<para>&a.archie;</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="staff-doc">
<title>The FreeBSD Documentation Project</title>
<para>The <ulink URL="http://www.freebsd.org/docproj.html">FreeBSD
Documentation Project</ulink> is responsible for a number of
different services, each service being run by an individual and his
Documentation Project</ulink> is responsible for a number of different
services, each service being run by an individual and his
<emphasis>deputies</emphasis> (if any):</para>
<variablelist>
<varlistentry><term>Documentation Project Manager</term>
<varlistentry>
<term>Documentation Project Manager</term>
<listitem>
<para>&a.nik;</para>
</listitem>
</varlistentry>
<varlistentry><term>Webmaster</term>
<varlistentry>
<term>Webmaster</term>
<listitem>
<para>&a.wosch;</para>
</listitem>
</varlistentry>
<varlistentry><term>Handbook &amp; FAQ Editor</term>
<varlistentry>
<term>Handbook &amp; FAQ Editor</term>
<listitem>
<para>&a.faq;</para>
</listitem>
</varlistentry>
<varlistentry><term>News Editor</term>
<varlistentry>
<term>News Editor</term>
<listitem>
<para>&a.nsj;</para>
<para><emphasis>Deputy:</emphasis> &a.john;</para>
</listitem>
</varlistentry>
@ -636,7 +626,8 @@
</listitem>
</varlistentry>
<varlistentry><term>Gallery Editor</term>
<varlistentry>
<term>Gallery Editor</term>
<listitem>
<para>&a.nsj;</para>
@ -662,28 +653,32 @@
</listitem>
</varlistentry>
<varlistentry><term>Style Police &amp; Art Director</term>
<varlistentry>
<term>Style Police &amp; Art Director</term>
<listitem>
<para>&a.opsys;</para>
</listitem>
</varlistentry>
<varlistentry><term>Database Engineer</term>
<varlistentry>
<term>Database Engineer</term>
<listitem>
<para>&a.mayo;</para>
</listitem>
</varlistentry>
<varlistentry><term>CGI Engineer</term>
<varlistentry>
<term>CGI Engineer</term>
<listitem>
<para>&a.stb;</para>
</listitem>
</varlistentry>
<varlistentry><term>Bottle Washing</term>
<varlistentry>
<term>Bottle Washing</term>
<listitem>
<para>&a.nsj;</para>
@ -698,36 +693,35 @@
</listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="staff-who">
<title>Who Is Responsible for What</title>
<variablelist>
<varlistentry><term>Principal Architect</term>
<varlistentry>
<term>Principal Architect</term>
<listitem>
<para>&a.dg;</para>
</listitem>
</varlistentry>
<varlistentry><term><ulink
url="http://www.freebsd.org/docproj/docproj.html">Documentation Project Manager</ulink></term>
<varlistentry>
<term><ulink
url="http://www.freebsd.org/docproj/docproj.html">Documentation
Project Manager</ulink></term>
<listitem>
<para>&a.nik;</para>
</listitem>
</varlistentry>
<varlistentry><term><link linkend="l10n">Internationalization</link></term>
<varlistentry>
<term><link linkend="l10n">Internationalization</link></term>
<listitem>
<para>&a.ache;</para>
</listitem>
</varlistentry>
@ -735,44 +729,45 @@
<listitem>
<para>&a.wollman;</para>
</listitem>
</varlistentry>
<varlistentry><term><link linkend="eresources-mail">Postmaster</link></term>
<varlistentry>
<term><link linkend="eresources-mail">Postmaster</link></term>
<listitem>
<para>&a.jmb;</para>
</listitem>
</varlistentry>
<varlistentry><term>Release Coordinator</term>
<varlistentry>
<term>Release Coordinator</term>
<listitem>
<para>&a.jkh;</para>
</listitem>
</varlistentry>
<varlistentry><term>Public Relations &amp; Corporate
Liaison</term>
<varlistentry>
<term>Public Relations &amp; Corporate Liaison</term>
<listitem>
<para>&a.jkh;</para>
</listitem>
</varlistentry>
<varlistentry><term><ulink url="http://www.freebsd.org/security/">Security Officer</ulink></term>
<varlistentry>
<term><ulink url="http://www.freebsd.org/security/">Security
Officer</ulink></term>
<listitem>
<para>&a.imp;</para>
</listitem>
</varlistentry>
<varlistentry><term><ulink url="http://www.freebsd.org/support.html#cvs">>Source Repository Managers</ulink></term>
<varlistentry>
<term><ulink url="http://www.freebsd.org/support.html#cvs">>Source
Repository Managers</ulink></term>
<listitem>
<para>Principal: &a.peter;</para>
@ -780,54 +775,54 @@
<para>Assistant: &a.jdp;</para>
<para>International (Crypto): &a.markm;</para>
</listitem>
</varlistentry>
<varlistentry><term><ulink url="http://www.freebsd.org/ports/">Ports Manager</ulink></term>
<listitem>
<para>&a.asami;</para>
</listitem>
</varlistentry>
<varlistentry><term>XFree86 Project, Inc. Liaison</term>
<listitem>
<para>&a.rich;</para>
</listitem>
</varlistentry>
<varlistentry><term><link linkend="eresources-news">Usenet Support</link></term>
<listitem>
<para>&a.joerg;</para>
</listitem>
</varlistentry>
<varlistentry><term><ulink url="http://www.freebsd.org/support.html#gnats">GNATS Administrator</ulink></term>
<listitem>
<para>&a.steve;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url="http://www.freebsd.org/internal/">Webmaster</ulink></term>
<term><ulink url="http://www.freebsd.org/ports/">Ports
Manager</ulink></term>
<listitem>
<para>&a.asami;</para>
</listitem>
</varlistentry>
<varlistentry>
<term>XFree86 Project, Inc. Liaison</term>
<listitem>
<para>&a.rich;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><link linkend="eresources-news">Usenet Support</link></term>
<listitem>
<para>&a.joerg;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url="http://www.freebsd.org/support.html#gnats">GNATS
Administrator</ulink></term>
<listitem>
<para>&a.steve;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink
url="http://www.freebsd.org/internal/">Webmaster</ulink></term>
<listitem>
<para>&a.wosch;</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
</chapter>
</chapter>
<!--
Local Variables:

11
en_US.ISO_8859-1/books/handbook/x11/chapter.sgml
View file

@ -1,11 +1,10 @@
<chapter id="x11">
<chapter id="x11">
<title>The X Window System</title>
<para>Pending the completion of this section, please refer to
documentation supplied by the <ulink URL="http://www.xfree86.org/">The
XFree86 Project, Inc</ulink>.</para>
</chapter>
<para>Pending the completion of this section, please refer to documentation
supplied by the <ulink URL="http://www.xfree86.org/">The XFree86 Project,
Inc</ulink>.</para>
</chapter>
<!--
Local Variables:

3195
en_US.ISO_8859-1/books/porters-handbook/book.sgml
View file

File diff suppressed because it is too large Load diff