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

"doc/en. The time has come. Prepare yourself."

Browse source 
"No, wait, I don't want t--" <blam>

"Goodbye".
This commit is contained in:
Nik Clayton 1999-08-21 18:13:33 +00:00
parent c49d00f601
commit dddae37958
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=5413
78 changed files with 0 additions and 61496 deletions
Download patch file Download diff file Expand all files Collapse all files

5
en/Makefile
View file

@ -1,5 +0,0 @@
# $Id: Makefile,v 1.1 1999-03-08 21:43:32 nik Exp $
SUBDIR = handbook
.include <bsd.subdir.mk>

58
en/handbook/Makefile
View file

@ -1,58 +0,0 @@
#
# $Id: Makefile,v 1.21 1999-05-05 20:31:23 nik Exp $
#
# Build the FreeBSD Handbook.
#
MAINTAINER=nik@FreeBSD.ORG
DOC?= handbook
FORMATS?= html-split
INSTALL_COMPRESSED?= gz
INSTALL_ONLY_COMPRESSED?=
#
# SRCS lists the individual SGML files that make up the document. Changes
# to any of these files will force a rebuild
#
# SGML content
SRCS= handbook.sgml
SRCS+= advanced-networking/chapter.sgml
SRCS+= backups/chapter.sgml
SRCS+= basics/chapter.sgml
SRCS+= bibliography/chapter.sgml
SRCS+= contrib/chapter.sgml
SRCS+= cutting-edge/chapter.sgml
SRCS+= disks/chapter.sgml
SRCS+= eresources/chapter.sgml
SRCS+= hw/chapter.sgml
SRCS+= install/chapter.sgml
SRCS+= internals/chapter.sgml
SRCS+= introduction/chapter.sgml
SRCS+= kernelconfig/chapter.sgml
SRCS+= kerneldebug/chapter.sgml
SRCS+= kernelopts/chapter.sgml
SRCS+= l10n/chapter.sgml
SRCS+= linuxemu/chapter.sgml
SRCS+= mail/chapter.sgml
SRCS+= mirrors/chapter.sgml
SRCS+= pgpkeys/chapter.sgml
SRCS+= policies/chapter.sgml
SRCS+= ppp-and-slip/chapter.sgml
SRCS+= printing/chapter.sgml
SRCS+= quotas/chapter.sgml
SRCS+= security/chapter.sgml
SRCS+= serialcomms/chapter.sgml
SRCS+= staff/chapter.sgml
SRCS+= x11/chapter.sgml
SRCS+= ports/chapter.sgml
# Entities
SRCS+= authors.ent
SRCS+= chapters.ent
SRCS+= mailing-lists.ent
.include "../../share/mk/docproj.docbook.mk"

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

@ -1,934 +0,0 @@
<!--
The FreeBSD Documentation Project
$Id: chapter.sgml,v 1.12 1999-07-28 20:23:15 nik Exp $
-->
<chapter id="advanced-networking">
<title>Advanced Networking</title>
<sect1 id="routing">
<title>Gateways and Routes</title>
<para><emphasis>Contributed by &a.gryphon;. 6 October
1995.</emphasis></para>
<para>For one machine to be able to find another, there must be a
mechanism in place to describe how to get from one to the other. This is
called Routing. A &ldquo;route&rdquo; is a defined pair of addresses: a
&ldquo;destination&rdquo; and a &ldquo;gateway&rdquo;. The pair
indicates that if you are trying to get to this
<emphasis>destination</emphasis>, send along through this
<emphasis>gateway</emphasis>. There are three types of destinations:
individual hosts, subnets, and &ldquo;default&rdquo;. The
&ldquo;default route&rdquo; is used if none of the other routes apply.
We will talk a little bit more about default routes later on. There are
also three types of gateways: individual hosts, interfaces (also called
&ldquo;links&rdquo;), and ethernet hardware addresses.</para>
<sect2>
<title>An example</title>
<para>To illustrate different aspects of routing, we will use the
following example which is the output of the command <command>netstat
-r</command>:</para>
<screen>Destination Gateway Flags Refs Use Netif Expire
default outside-gw UGSc 37 418 ppp0
localhost localhost UH 0 181 lo0
test0 0:e0:b5:36:cf:4f UHLW 5 63288 ed0 77
10.20.30.255 link#1 UHLW 1 2421
foobar.com link#1 UC 0 0
host1 0:e0:a8:37:8:1e UHLW 3 4601 lo0
host2 0:e0:a8:37:8:1e UHLW 0 5 lo0 =>
host2.foobar.com link#1 UC 0 0
224 link#1 UC 0 0</screen>
<para>The first two lines specify the default route (which we will cover
in the next section) and the <hostid>localhost</hostid> route.</para>
<para>The interface (<literal>Netif</literal> column) that it specifies
to use for <literal>localhost</literal> is
<devicename>lo0</devicename>, also known as the loopback device. This
says to keep all traffic for this destination internal, rather than
sending it out over the LAN, since it will only end up back where it
started anyway.</para>
<para>The next thing that stands out are the <hostid
role="mac">0:e0:...</hostid> addresses. These are ethernet hardware
addresses. FreeBSD will automatically identify any hosts
(<hostid>test0</hostid> in the example) on the local ethernet and add
a route for that host, directly to it over the ethernet interface,
<devicename>ed0</devicename>. There is also a timeout
(<literal>Expire</literal> column) associated with this type of route,
which is used if we fail to hear from the host in a specific amount of
time. In this case the route will be automatically deleted. These
hosts are identified using a mechanism known as RIP (Routing
Information Protocol), which figures out routes to local hosts based
upon a shortest path determination.</para>
<para>FreeBSD will also add subnet routes for the local subnet (<hostid
role="ipaddr">10.20.30.255</hostid> is the broadcast address for the
subnet <hostid role="ipaddr">10.20.30</hostid>, and <hostid
role="domainname">foobar.com</hostid> is the domain name associated
with that subnet). The designation <literal>link#1</literal> refers
to the first ethernet card in the machine. You will notice no
additional interface is specified for those.</para>
<para>Both of these groups (local network hosts and local subnets) have
their routes automatically configured by a daemon called
<command>routed</command>. If this is not run, then only routes which
are statically defined (ie. entered explicitly) will exist.</para>
<para>The <literal>host1</literal> line refers to our host, which it
knows by ethernet address. Since we are the sending host, FreeBSD
knows to use the loopback interface (<devicename>lo0</devicename>)
rather than sending it out over the ethernet interface.</para>
<para>The two <literal>host2</literal> lines are an example of what
happens when we use an ifconfig alias (see the section of ethernet for
reasons why we would do this). The <literal>=&gt;</literal> symbol
after the <devicename>lo0</devicename> interface says that not only
are we using the loopback (since this is address also refers to the
local host), but specifically it is an alias. Such routes only show
up on the host that supports the alias; all other hosts on the local
network will simply have a <literal>link#1</literal> line for
such.</para>
<para>The final line (destination subnet <literal>224</literal>) deals
with MultiCasting, which will be covered in a another section.</para>
<para>The other column that we should talk about are the
<literal>Flags</literal>. Each route has different attributes that
are described in the column. Below is a short table of some of these
flags and their meanings:</para>
<informaltable frame="none">
<tgroup cols="2">
<tbody>
<row>
<entry>U</entry>
<entry>Up: The route is active.</entry>
</row>
<row>
<entry>H</entry>
<entry>Host: The route destination is a single host.</entry>
</row>
<row>
<entry>G</entry>
<entry>Gateway: Send anything for this destination on to this
remote system, which will figure out from there where to send
it.</entry>
</row>
<row>
<entry>S</entry>
<entry>Static: This route was configured manually, not
automatically generated by the system.</entry>
</row>
<row>
<entry>C</entry>
<entry>Clone: Generates a new route based upon this route for
machines we connect to. This type of route is normally used
for local networks.</entry>
</row>
<row>
<entry>W</entry>
<entry>WasCloned: Indicated a route that was auto-configured
based upon a local area network (Clone) route.</entry>
</row>
<row>
<entry>L</entry>
<entry>Link: Route involves references to ethernet
hardware.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect2>
<sect2>
<title>Default routes</title>
<para>When the local system needs to make a connection to remote host,
it checks the routing table to determine if a known path exists. If
the remote host falls into a subnet that we know how to reach (Cloned
routes), then the system checks to see if it can connect along that
interface.</para>
<para>If all known paths fail, the system has one last option: the
&ldquo;default&rdquo; route. This route is a special type of gateway
route (usually the only one present in the system), and is always
marked with a <literal>c</literal> in the flags field. For hosts on a
local area network, this gateway is set to whatever machine has a
direct connection to the outside world (whether via PPP link, or your
hardware device attached to a dedicated data line).</para>
<para>If you are configuring the default route for a machine which
itself is functioning as the gateway to the outside world, then the
default route will be the gateway machine at your Internet Service
Provider's (ISP) site.</para>
<para>Let us look at an example of default routes. This is a common
configuration:</para>
<literallayout>
[Local2] &lt;--ether--&gt; [Local1] &lt;--PPP--&gt; [ISP-Serv] &lt;--ether--&gt; [T1-GW]
</literallayout>
<para>The hosts <hostid>Local1</hostid> and <hostid>Local2</hostid> are
at your site, with the formed being your PPP connection to your ISP's
Terminal Server. Your ISP has a local network at their site, which
has, among other things, the server where you connect and a hardware
device (T1-GW) attached to the ISP's Internet feed.</para>
<para>The default routes for each of your machines will be:</para>
<informaltable frame="none">
<tgroup cols="3">
<thead>
<row>
<entry>host</entry>
<entry>default gateway</entry>
<entry>interface</entry>
</row>
</thead>
<tbody>
<row>
<entry>Local2</entry>
<entry>Local1</entry>
<entry>ethernet</entry>
</row>
<row>
<entry>Local1</entry>
<entry>T1-GW</entry>
<entry>PPP</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>A common question is &ldquo;Why (or how) would we set the T1-GW to
be the default gateway for Local1, rather than the ISP server it is
connected to?&rdquo;.</para>
<para>Remember, since the PPP interface is using an address on the ISP's
local network for your side of the connection, routes for any other
machines on the ISP's local network will be automatically generated.
Hence, you will already know how to reach the T1-GW machine, so there
is no need for the intermediate step of sending traffic to the ISP
server.</para>
<para>As a final note, it is common to use the address <hostid
role="ipaddr">...1</hostid> as the gateway address for your local
network. So (using the same example), if your local class-C address
space was <hostid role="ipaddr">10.20.30</hostid> and your ISP was
using <hostid role="ipaddr">10.9.9</hostid> then the default routes
would be:</para>
<literallayout>
Local2 (10.20.30.2) --&gt; Local1 (10.20.30.1)
Local1 (10.20.30.1, 10.9.9.30) --&gt; T1-GW (10.9.9.1)
</literallayout>
</sect2>
<sect2>
<title>Dual homed hosts</title>
<para>There is one other type of configuration that we should cover, and
that is a host that sits on two different networks. Technically, any
machine functioning as a gateway (in the example above, using a PPP
connection) counts as a dual-homed host. But the term is really only
used to refer to a machine that sits on two local-area
networks.</para>
<para>In one case, the machine as two ethernet cards, each having an
address on the separate subnets. Alternately, the machine may only
have one ethernet card, and be using ifconfig aliasing. The former is
used if two physically separate ethernet networks are in use, the
latter if there is one physical network segment, but two logically
separate subnets.</para>
<para>Either way, routing tables are set up so that each subnet knows
that this machine is the defined gateway (inbound route) to the other
subnet. This configuration, with the machine acting as a Bridge
between the two subnets, is often used when we need to implement
packet filtering or firewall security in either or both
directions.</para>
</sect2>
<sect2>
<title>Routing propagation</title>
<para>We have already talked about how we define our routes to the
outside world, but not about how the outside world finds us.</para>
<para>We already know that routing tables can be set up so that all
traffic for a particular address space (in our examples, a class-C
subnet) can be sent to a particular host on that network, which will
forward the packets inbound.</para>
<para>When you get an address space assigned to your site, your service
provider will set up their routing tables so that all traffic for your
subnet will be sent down your PPP link to your site. But how do sites
across the country know to send to your ISP?</para>
<para>There is a system (much like the distributed DNS information) that
keeps track of all assigned address-spaces, and defines their point of
connection to the Internet Backbone. The &ldquo;Backbone&rdquo; are
the main trunk lines that carry Internet traffic across the country,
and around the world. Each backbone machine has a copy of a master
set of tables, which direct traffic for a particular network to a
specific backbone carrier, and from there down the chain of service
providers until it reaches your network.</para>
<para>It is the task of your service provider to advertise to the
backbone sites that they are the point of connection (and thus the
path inward) for your site. This is known as route
propagation.</para>
</sect2>
<sect2>
<title>Troubleshooting</title>
<para>Sometimes, there is a problem with routing propagation, and some
sites are unable to connect to you. Perhaps the most useful command
for trying to figure out where a routing is breaking down is the
&man.traceroute.8; command. It is equally useful if you cannot seem
to make a connection to a remote machine (i.e. &man.ping.8;
fails).</para>
<para>The &man.traceroute.8; command is run with the name of the remote
host you are trying to connect to. It will show the gateway hosts
along the path of the attempt, eventually either reaching the target
host, or terminating because of a lack of connection.</para>
<para>For more information, see the manual page for
&man.traceroute.8;.</para>
</sect2>
</sect1>
<sect1 id="nfs">
<title>NFS</title>
<para><emphasis>Contributed by &a.jlind;.</emphasis></para>
<para>Certain Ethernet adapters for ISA PC systems have limitations which
can lead to serious network problems, particularly with NFS. This
difficulty is not specific to FreeBSD, but FreeBSD systems are affected
by it.</para>
<para>The problem nearly always occurs when (FreeBSD) PC systems are
networked with high-performance workstations, such as those made by
Silicon Graphics, Inc., and Sun Microsystems, Inc. The NFS mount will
work fine, and some operations may succeed, but suddenly the server will
seem to become unresponsive to the client, even though requests to and
from other systems continue to be processed. This happens to the client
system, whether the client is the FreeBSD system or the workstation. On
many systems, there is no way to shut down the client gracefully once
this problem has manifested itself. The only solution is often to reset
the client, because the NFS situation cannot be resolved.</para>
<para>Though the &ldquo;correct&rdquo; solution is to get a higher
performance and capacity Ethernet adapter for the FreeBSD system, there
is a simple workaround that will allow satisfactory operation. If the
FreeBSD system is the <emphasis>server</emphasis>, include the option
<option>-w=1024</option> on the mount from the client. If the FreeBSD
system is the <emphasis>client</emphasis>, then mount the NFS file
system with the option <option>-r=1024</option>. These options may be
specified using the fourth field of the <filename>fstab</filename> entry
on the client for automatic mounts, or by using the <option>-o</option>
parameter of the mount command for manual mounts.</para>
<para>It should be noted that there is a different problem, sometimes
mistaken for this one, when the NFS servers and clients are on different
networks. If that is the case, make <emphasis>certain</emphasis> that
your routers are routing the necessary UDP information, or you will not
get anywhere, no matter what else you are doing.</para>
<para>In the following examples, <hostid>fastws</hostid> is the host
(interface) name of a high-performance workstation, and
<hostid>freebox</hostid> is the host (interface) name of a FreeBSD
system with a lower-performance Ethernet adapter. Also,
<filename>/sharedfs</filename> will be the exported NFS filesystem (see
<command>man exports</command>), and <filename>/project</filename> will
be the mount point on the client for the exported file system. In all
cases, note that additional options, such as <option>hard</option> or
<option>soft</option> and <option>bg</option> may be desirable in your
application.</para>
<para>Examples for the FreeBSD system (<hostid>freebox</hostid>) as the
client: in <filename>/etc/fstab</filename> on freebox:</para>
<programlisting>
fastws:/sharedfs /project nfs rw,-r=1024 0 0</programlisting>
<para>As a manual mount command on <hostid>freebox</hostid>:</para>
<screen>&prompt.root; <userinput>mount -t nfs -o -r=1024 fastws:/sharedfs /project</userinput></screen>
<para>Examples for the FreeBSD system as the server: in
<filename>/etc/fstab</filename> on <hostid>fastws</hostid>:</para>
<programlisting>
freebox:/sharedfs /project nfs rw,-w=1024 0 0</programlisting>
<para>As a manual mount command on <hostid>fastws</hostid>:</para>
<screen>&prompt.root; <userinput>mount -t nfs -o -w=1024 freebox:/sharedfs /project</userinput></screen>
<para>Nearly any 16-bit Ethernet adapter will allow operation without the
above restrictions on the read or write size.</para>
<para>For anyone who cares, here is what happens when the failure occurs,
which also explains why it is unrecoverable. NFS typically works with a
&ldquo;block&rdquo; size of 8k (though it may do fragments of smaller
sizes). Since the maximum Ethernet packet is around 1500 bytes, the NFS
&ldquo;block&rdquo; gets split into multiple Ethernet packets, even
though it is still a single unit to the upper-level code, and must be
received, assembled, and <emphasis>acknowledged</emphasis> as a unit.
The high-performance workstations can pump out the packets which
comprise the NFS unit one right after the other, just as close together
as the standard allows. On the smaller, lower capacity cards, the later
packets overrun the earlier packets of the same unit before they can be
transferred to the host and the unit as a whole cannot be reconstructed
or acknowledged. As a result, the workstation will time out and try
again, but it will try again with the entire 8K unit, and the process
will be repeated, ad infinitum.</para>
<para>By keeping the unit size below the Ethernet packet size limitation,
we ensure that any complete Ethernet packet received can be acknowledged
individually, avoiding the deadlock situation.</para>
<para>Overruns may still occur when a high-performance workstations is
slamming data out to a PC system, but with the better cards, such
overruns are not guaranteed on NFS &ldquo;units&rdquo;. When an overrun
occurs, the units affected will be retransmitted, and there will be a
fair chance that they will be received, assembled, and
acknowledged.</para>
</sect1>
<sect1 id="diskless">
<title>Diskless Operation</title>
<para><emphasis>Contributed by &a.martin;.</emphasis></para>
<para><filename>netboot.com</filename>/<filename>netboot.rom</filename>
allow you to boot your FreeBSD machine over the network and run FreeBSD
without having a disk on your client. Under 2.0 it is now possible to
have local swap. Swapping over NFS is also still supported.</para>
<para>Supported Ethernet cards include: Western Digital/SMC 8003, 8013,
8216 and compatibles; NE1000/NE2000 and compatibles (requires
recompile)</para>
<sect2>
<title>Setup Instructions</title>
<procedure>
<step>
<para>Find a machine that will be your server. This machine will
require enough disk space to hold the FreeBSD 2.0 binaries and
have bootp, tftp and NFS services available. Tested
machines:</para>
<itemizedlist>
<listitem>
<para>HP9000/8xx running HP-UX 9.04 or later (pre 9.04 doesn't
work)</para>
</listitem>
<listitem>
<para>Sun/Solaris 2.3. (you may need to get bootp)</para>
</listitem>
</itemizedlist>
</step>
<step>
<para>Set up a bootp server to provide the client with IP, gateway,
netmask.</para>
<programlisting>
diskless:\
:ht=ether:\
:ha=0000c01f848a:\
:sm=255.255.255.0:\
:hn:\
:ds=192.1.2.3:\
:ip=192.1.2.4:\
:gw=192.1.2.5:\
:vm=rfc1048:</programlisting>
</step>
<step>
<para>Set up a TFTP server (on same machine as bootp server) to
provide booting information to client. The name of this file is
<filename>cfg.<replaceable>X.X.X.X</replaceable></filename> (or
<filename>/tftpboot/cfg.<replaceable>X.X.X.X</replaceable></filename>,
it will try both) where <replaceable>X.X.X.X</replaceable> is the
IP address of the client. The contents of this file can be any
valid netboot commands. Under 2.0, netboot has the following
commands:</para>
<informaltable frame="none">
<tgroup cols="2">
<tbody>
<row>
<entry>help</entry>
<entry>print help list</entry>
</row>
<row>
<entry>ip
<option><replaceable>X.X.X.X</replaceable></option></entry>
<entry>print/set client's IP address</entry>
</row>
<row>
<entry>server
<option><replaceable>X.X.X.X</replaceable></option></entry>
<entry>print/set bootp/tftp server address</entry>
</row>
<row>
<entry>netmask
<option><replaceable>X.X.X.X</replaceable></option></entry>
<entry>print/set netmask</entry>
</row>
<row>
<entry>hostname <replaceable>name</replaceable></entry>
<entry>print/set hostname</entry>
</row>
<row>
<entry>kernel
<option><replaceable>name</replaceable></option></entry>
<entry>print/set kernel name</entry>
</row>
<row>
<entry>rootfs
<option><replaceable>ip:/fs</replaceable></option></entry>
<entry>print/set root filesystem</entry>
</row>
<row>
<entry>swapfs
<option><replaceable>ip:/fs</replaceable></option></entry>
<entry>print/set swap filesystem</entry>
</row>
<row>
<entry>swapsize
<option><replaceable>size</replaceable></option></entry>
<entry>set diskless swapsize in Kbytes</entry>
</row>
<row>
<entry>diskboot</entry>
<entry>boot from disk</entry>
</row>
<row>
<entry>autoboot</entry>
<entry>continue boot process</entry>
</row>
<row>
<entry>trans
<option>on</option>|<option>off</option></entry>
<entry>turn transceiver on|off</entry>
</row>
<row>
<entry>flags
<option>b</option><option>c</option><option>d</option><option>h</option><option>s</option><option>v</option></entry>
<entry>set boot flags</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>A typical completely diskless cfg file might contain:</para>
<programlisting>
rootfs 192.1.2.3:/rootfs/myclient
swapfs 192.1.2.3:/swapfs
swapsize 20000
hostname myclient.mydomain</programlisting>
<para>A cfg file for a machine with local swap might contain:</para>
<programlisting>
rootfs 192.1.2.3:/rootfs/myclient
hostname myclient.mydomain</programlisting>
</step>
<step>
<para>Ensure that your NFS server has exported the root (and swap if
applicable) filesystems to your client, and that the client has
root access to these filesystems A typical
<filename>/etc/exports</filename> file on FreeBSD might look
like:</para>
<programlisting>
/rootfs/myclient -maproot=0:0 myclient.mydomain
/swapfs -maproot=0:0 myclient.mydomain</programlisting>
<para>And on HP-UX:</para>
<programlisting>
/rootfs/myclient -root=myclient.mydomain
/swapfs -root=myclient.mydomain</programlisting>
</step>
<step>
<para>If you are swapping over NFS (completely diskless
configuration) create a swap file for your client using
<command>dd</command>. If your <command>swapfs</command> command
has the arguments <filename>/swapfs</filename> and the size 20000
as in the example above, the swapfile for myclient will be called
<filename>/swapfs/swap.<replaceable>X.X.X.X</replaceable></filename>
where <replaceable>X.X.X.X</replaceable> is the client's IP addr,
eg:</para>
<screen>&prompt.root; <userinput>dd if=/dev/zero of=/swapfs/swap.192.1.2.4 bs=1k count=20000</userinput></screen>
<para>Also, the client's swap space might contain sensitive
information once swapping starts, so make sure to restrict read
and write access to this file to prevent unauthorized
access:</para>
<screen>&prompt.root; <userinput>chmod 0600 /swapfs/swap.192.1.2.4</userinput></screen>
</step>
<step>
<para>Unpack the root filesystem in the directory the client will
use for its root filesystem (<filename>/rootfs/myclient</filename>
in the example above).</para>
<itemizedlist>
<listitem>
<para>On HP-UX systems: The server should be running HP-UX 9.04
or later for HP9000/800 series machines. Prior versions do not
allow the creation of device files over NFS.</para>
</listitem>
<listitem>
<para>When extracting <filename>/dev</filename> in
<filename>/rootfs/myclient</filename>, beware that some
systems (HPUX) will not create device files that FreeBSD is
happy with. You may have to go to single user mode on the
first bootup (press control-c during the bootup phase), cd
<filename>/dev</filename> and do a <command>sh ./MAKEDEV
all</command> from the client to fix this.</para>
</listitem>
</itemizedlist>
</step>
<step>
<para>Run <command>netboot.com</command> on the client or make an
EPROM from the <filename>netboot.rom</filename> file</para>
</step>
</procedure>
</sect2>
<sect2>
<title>Using Shared <filename>/</filename> and <filename>/usr</filename>
filesystems</title>
<para>At present there isn't an officially sanctioned way of doing this,
although I have been using a shared <filename>/usr</filename>
filesystem and individual <filename>/</filename> filesystems for each
client. If anyone has any suggestions on how to do this cleanly,
please let me and/or the &a.core; know.</para>
</sect2>
<sect2>
<title>Compiling netboot for specific setups</title>
<para>Netboot can be compiled to support NE1000/2000 cards by changing
the configuration in
<filename>/sys/i386/boot/netboot/Makefile</filename>. See the
comments at the top of this file.</para>
</sect2>
</sect1>
<sect1 id="isdn">
<title>ISDN</title>
<para><emphasis>Last modified by &a.wlloyd;</emphasis>.</para>
<para>A good resource for information on ISDN technology and hardware is
<ulink URL="http://alumni.caltech.edu/~dank/isdn/">Dan Kegel's ISDN
Page</ulink>.</para>
<para>A quick simple roadmap to ISDN follows:</para>
<itemizedlist>
<listitem>
<para>If you live in Europe I suggest you investigate the ISDN card
section.</para>
</listitem>
<listitem>
<para>If you are planning to use ISDN primarily to connect to the
Internet with an Internet Provider on a dialup non-dedicated basis,
I suggest you look into Terminal Adapters. This will give you the
most flexibility, with the fewest problems, if you change
providers.</para>
</listitem>
<listitem>
<para>If you are connecting two lans together, or connecting to the
Internet with a dedicated ISDN connection, I suggest you consider
the stand alone router/bridge option.</para>
</listitem>
</itemizedlist>
<para>Cost is a significant factor in determining what solution you will
choose. The following options are listed from least expensive to most
expensive.</para>
<sect2>
<title>ISDN Cards</title>
<para><emphasis>Contributed by &a.hm;.</emphasis></para>
<para>This section is really only relevant to ISDN users in countries
where the DSS1/Q.931 ISDN standard is supported.</para>
<para>Some growing number of PC ISDN cards are supported under FreeBSD
2.2.x and up by the isdn4bsd driver package. It is still under
development but the reports show that it is successfully used all over
Europe.</para>
<para>The latest isdn4bsd version is available from <ulink
url="ftp://isdn4bsd@ftp.consol.de/pub/">ftp://isdn4bsd@ftp.consol.de/pub/</ulink>,
the main isdn4bsd ftp site (you have to log in as user
<username>isdn4bsd</username> , give your mail address as the password
and change to the <filename>pub</filename> directory. Anonymous ftp
as user <username>ftp</username> or <username>anonymous</username>
will <emphasis>not</emphasis> give the desired result).</para>
<para>Isdn4bsd allows you to connect to other ISDN routers using either
IP over raw HDLC or by using synchronous PPP. A telephone answering
machine application is also available.</para>
<para>Many ISDN PC cards are supported, mostly the ones with a Siemens
ISDN chipset (ISAC/HSCX), support for other chipsets (from Motorola,
Cologne Chip Designs) is currently under development. For an
up-to-date list of supported cards, please have a look at the <ulink
url="ftp://isdn4bsd@ftp.consol.de/pub/README">README</ulink>
file.</para>
<para>In case you are interested in adding support for a different ISDN
protocol, a currently unsupported ISDN PC card or otherwise enhancing
isdn4bsd, please get in touch with <email>hm@kts.org</email>.</para>
<para>A majordomo maintained mailing list is available. To join the
list, send mail to <email>majordomo@FreeBSD.org</email> and
specify:</para>
<programlisting>
subscribe freebsd-isdn</programlisting>
<para>in the body of your message.</para>
</sect2>
<sect2>
<title>ISDN Terminal Adapters</title>
<para>Terminal adapters(TA), are to ISDN what modems are to regular
phone lines.</para>
<para>Most TA's use the standard hayes modem AT command set, and can be
used as a drop in replacement for a modem.</para>
<para>A TA will operate basically the same as a modem except connection
and throughput speeds will be much faster than your old modem. You
will need to configure <link linkend="ppp">PPP</link> exactly the same
as for a modem setup. Make sure you set your serial speed as high as
possible.</para>
<para>The main advantage of using a TA to connect to an Internet
Provider is that you can do Dynamic PPP. As IP address space becomes
more and more scarce, most providers are not willing to provide you
with a static IP anymore. Most standalone routers are not able to
accommodate dynamic IP allocation.</para>
<para>TA's completely rely on the PPP daemon that you are running for
their features and stability of connection. This allows you to
upgrade easily from using a modem to ISDN on a FreeBSD machine, if you
already have PPP setup. However, at the same time any problems you
experienced with the PPP program and are going to persist.</para>
<para>If you want maximum stability, use the kernel <link
linkend="ppp">PPP</link> option, not the user-land <link
linkend="userppp">iijPPP</link>.</para>
<para>The following TA's are know to work with FreeBSD.</para>
<itemizedlist>
<listitem>
<para>Motorola BitSurfer and Bitsurfer Pro</para>
</listitem>
<listitem>
<para>Adtran</para>
</listitem>
</itemizedlist>
<para>Most other TA's will probably work as well, TA vendors try to make
sure their product can accept most of the standard modem AT command
set.</para>
<para>The real problem with external TA's is like modems you need a good
serial card in your computer.</para>
<para>You should read the <link linkend="uart">serial ports</link>
section in the handbook for a detailed understanding of serial
devices, and the differences between asynchronous and synchronous
serial ports.</para>
<para>A TA running off a standard PC serial port (asynchronous) limits
you to 115.2Kbs, even though you have a 128Kbs connection. To fully
utilize the 128Kbs that ISDN is capable of, you must move the TA to a
synchronous serial card.</para>
<para>Do not be fooled into buying an internal TA and thinking you have
avoided the synchronous/asynchronous issue. Internal TA's simply have
a standard PC serial port chip built into them. All this will do, is
save you having to buy another serial cable, and find another empty
electrical socket.</para>
<para>A synchronous card with a TA is at least as fast as a standalone
router, and with a simple 386 FreeBSD box driving it, probably more
flexible.</para>
<para>The choice of sync/TA vs standalone router is largely a religious
issue. There has been some discussion of this in the mailing lists.
I suggest you search the <ulink
URL="http://www.FreeBSD.org/search.html">archives</ulink> for the
complete discussion.</para>
</sect2>
<sect2>
<title>Standalone ISDN Bridges/Routers</title>
<para>ISDN bridges or routers are not at all specific to FreeBSD or any
other operating system. For a more complete description of routing
and bridging technology, please refer to a Networking reference
book.</para>
<para>In the context of this page, I will use router and bridge
interchangeably.</para>
<para>As the cost of low end ISDN routers/bridges comes down, it will
likely become a more and more popular choice. An ISDN router is a
small box that plugs directly into your local Ethernet network(or
card), and manages its own connection to the other bridge/router. It
has all the software to do PPP and other protocols built in.</para>
<para>A router will allow you much faster throughput that a standard TA,
since it will be using a full synchronous ISDN connection.</para>
<para>The main problem with ISDN routers and bridges is that
interoperability between manufacturers can still be a problem. If you
are planning to connect to an Internet provider, I recommend that you
discuss your needs with them.</para>
<para>If you are planning to connect two lan segments together, ie: home
lan to the office lan, this is the simplest lowest maintenance
solution. Since you are buying the equipment for both sides of the
connection you can be assured that the link will work.</para>
<para>For example to connect a home computer or branch office network to
a head office network the following setup could be used.</para>
<example>
<title>Branch office or Home network</title>
<para>Network is 10 Base T Ethernet. Connect router to network cable
with AUI/10BT transceiver, if necessary.</para>
<!-- This should be a graphic -->
<programlisting>
---Sun workstation
|
---FreeBSD box
|
---Windows 95 (Do not admit to owning it)
|
Standalone router
|
ISDN BRI line</programlisting>
<para>If your home/branch office is only one computer you can use a
twisted pair crossover cable to connect to the standalone router
directly.</para>
</example>
<example>
<title>Head office or other lan</title>
<para>Network is Twisted Pair Ethernet.</para>
<!-- This should be a graphic -->
<programlisting>
-------Novell Server
| H |
| ---Sun
| |
| U ---FreeBSD
| |
| ---Windows 95
| B |
|___---Standalone router
|
ISDN BRI line</programlisting>
</example>
<para>One large advantage of most routers/bridges is that they allow you
to have 2 <emphasis>separate independent</emphasis> PPP connections to
2 separate sites at the <emphasis>same</emphasis> time. This is not
supported on most TA's, except for specific(expensive) models that
have two serial ports. Do not confuse this with channel bonding, MPP
etc.</para>
<para>This can be very useful feature, for example if you have an
dedicated internet ISDN connection at your office and would like to
tap into it, but don't want to get another ISDN line at work. A router
at the office location can manage a dedicated B channel connection
(64Kbs) to the internet, as well as a use the other B channel for a
separate data connection. The second B channel can be used for
dialin, dialout or dynamically bond(MPP etc.) with the first B channel
for more bandwidth.</para>
<para>An Ethernet bridge will also allow you to transmit more than just
IP traffic, you can also send IPX/SPX or whatever other protocols you
use.</para>
</sect2>
</sect1>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->

399
en/handbook/authors.ent
View file

@ -1,399 +0,0 @@
<!--
Names and email address of contributing authors and CVS committers.
Entity names for committers should be the same as their login names on
freefall.FreeBSD.org.
Use these entities when referencing people.
Please keep this list in alphabetical order by entity names.
$Id: authors.ent,v 1.43 1999-08-11 13:53:12 alfred Exp $
-->
<!ENTITY a.abial "Andrzej Bialecki <email>abial@FreeBSD.org</email>">
<!ENTITY a.ache "Andrey A. Chernov <email>ache@FreeBSD.org</email>">
<!ENTITY a.adam "Adam David <email>adam@FreeBSD.org</email>">
<!ENTITY a.alc "Alan L. Cox <email>alc@FreeBSD.org</email>">
<!ENTITY a.alex "Alex Nash <email>alex@FreeBSD.org</email>">
<!ENTITY a.alfred "Alfred Perlstein <email>alfred@FreeBSD.org</email>">
<!ENTITY a.amurai "Atsushi Murai <email>amurai@FreeBSD.org</email>">
<!ENTITY a.andreas "Andreas Klemm <email>andreas@FreeBSD.org</email>">
<!ENTITY a.archie "Archie Cobbs <email>archie@FreeBSD.org</email>">
<!ENTITY a.asami "Satoshi Asami <email>asami@FreeBSD.org</email>">
<!ENTITY a.ats "Andreas Schulz <email>ats@FreeBSD.org</email>">
<!ENTITY a.awebster "Andrew Webster <email>awebster@pubnix.net</email>">
<!ENTITY a.bde "Bruce Evans <email>bde@FreeBSD.org</email>">
<!ENTITY a.billf "Bill Fumerola <email>billf@FreeBSD.org</email>">
<!ENTITY a.brandon "Brandon Gillespie <email>brandon@FreeBSD.org</email>">
<!ENTITY a.brian "Brian Somers <email>brian@FreeBSD.org</email>">
<!ENTITY a.cawimm "Charles A. Wimmer <email>cawimm@FreeBSD.org</email>">
<!ENTITY a.cg "Cameron Grant <email>cg@FreeBSD.org</email>">
<!ENTITY a.charnier "Philippe Charnier <email>charnier@FreeBSD.org</email>">
<!ENTITY a.chris "Chris Costello <email>chris@FreeBSD.org</email>">
<!ENTITY a.chuck "Chuck Robey <email>chuckr@glue.umd.edu</email>">
<!ENTITY a.chuckr "Chuck Robey <email>chuckr@FreeBSD.org</email>">
<!ENTITY a.cpiazza "Chris Piazza <email>cpiazza@FreeBSD.org</email>">
<!ENTITY a.cracauer "Martin Cracauer <email>cracauer@FreeBSD.org</email>">
<!ENTITY a.csgr "Geoff Rehmet <email>csgr@FreeBSD.org</email>">
<!ENTITY a.cwt "Chris Timmons <email>cwt@FreeBSD.org</email>">
<!ENTITY a.danny "Daniel O'Callaghan <email>danny@FreeBSD.org</email>">
<!ENTITY a.darrenr "Darren Reed <email>darrenr@FreeBSD.org</email>">
<!ENTITY a.davidn "David Nugent <email>davidn@blaze.net.au</email>">
<!ENTITY a.dbaker "Daniel Baker <email>dbaker@FreeBSD.org</email>">
<!ENTITY a.dburr "Donald Burr <email>dburr@FreeBSD.org</email>">
<!ENTITY a.dcs "Daniel C. Sobral <email>dcs@FreeBSD.org</email>">
<!ENTITY a.deischen "Daniel Eischen <email>deischen@FreeBSD.org</email>">
<!ENTITY a.des "Dag-Erling C. Sm&oslash;rgrav <email>des@FreeBSD.org</email>">
<!ENTITY a.dfr "Doug Rabson <email>dfr@FreeBSD.org</email>">
<!ENTITY a.dg "David Greenman <email>dg@FreeBSD.org</email>">
<!ENTITY a.dick "Richard Seaman Jr. <email>dick@FreeBSD.org</email>">
<!ENTITY a.dillon "Matthew Dillon <email>dillon@FreeBSD.org</email>">
<!ENTITY a.dima "Dima Ruban <email>dima@FreeBSD.org</email>">
<!ENTITY a.dirk "Dirk Fr&ouml;mberg <email>dirk@FreeBSD.org</email>">
<!ENTITY a.dirkvangulik "Dirk-Willem van Gulik <email>Dirk.vanGulik@jrc.it</email>">
<!ENTITY a.dt "Dmitrij Tejblum <email>dt@FreeBSD.org</email>">
<!ENTITY a.dufault "Peter Dufault <email>dufault@FreeBSD.org</email>">
<!ENTITY a.dwhite "Doug White <email>dwhite@FreeBSD.org</email>">
<!ENTITY a.dyson "John Dyson <email>dyson@FreeBSD.org</email>">
<!ENTITY a.eivind "Eivind Eklund <email>eivind@FreeBSD.org</email>">
<!ENTITY a.ejc "Eric J. Chet <email>ejc@FreeBSD.org</email>">
<!ENTITY a.erich "Eric L. Hernes <email>erich@FreeBSD.org</email>">
<!ENTITY a.faq "FAQ Maintainer <email>faq@FreeBSD.org</email>">
<!ENTITY a.fenner "Bill Fenner <email>fenner@FreeBSD.org</email>">
<!ENTITY a.flathill "Seiichirou Hiraoka <email>flathill@FreeBSD.org</email>">
<!ENTITY a.foxfair "Howard F. Hu <email>foxfair@FreeBSD.org</email>">
<!ENTITY a.fsmp "Steve Passe <email>fsmp@FreeBSD.org</email>">
<!ENTITY a.gallatin "Andrew Gallatin <email>gallatin@FreeBSD.org</email>">
<!ENTITY a.gclarkii "Gary Clark II <email>gclarkii@FreeBSD.org</email>">
<!ENTITY a.gehenna "Masahide MAEKAWA <email>gehenna@FreeBSD.org</email>">
<!ENTITY a.gena "Gennady B. Sorokopud <email>gena@NetVision.net.il</email>">
<!ENTITY a.ghelmer "Guy Helmer <email>ghelmer@cs.iastate.edu</email>">
<!ENTITY a.gibbs "Justin T. Gibbs <email>gibbs@FreeBSD.org</email>">
<!ENTITY a.gj "Gary Jennejohn <email>gj@FreeBSD.org</email>">
<!ENTITY a.gpalmer "Gary Palmer <email>gpalmer@FreeBSD.org</email>">
<!ENTITY a.graichen "Thomas Graichen <email>graichen@FreeBSD.org</email>">
<!ENTITY a.green "Brian F. Feldman <email>green@FreeBSD.org</email>">
<!ENTITY a.grog "Greg Lehey <email>grog@FreeBSD.org</email>">
<!ENTITY a.gryphon "Coranth Gryphon <email>gryphon@healer.com</email>">
<!ENTITY a.guido "Guido van Rooij <email>guido@FreeBSD.org</email>">
<!ENTITY a.hanai "Hiroyuki HANAI <email>hanai@FreeBSD.org</email>">
<!ENTITY a.handy "Brian N. Handy <email>handy@sxt4.physics.montana.edu</email>">
<!ENTITY a.helbig "Wolfgang Helbig <email>helbig@FreeBSD.org</email>">
<!ENTITY a.hm "Hellmuth Michaelis <email>hm@FreeBSD.org</email>">
<!ENTITY a.hoek "Tim Vanderhoek <email>hoek@FreeBSD.org</email>">
<!ENTITY a.hosokawa "Tatsumi Hosokawa <email>hosokawa@FreeBSD.org</email>">
<!ENTITY a.hsu "Jeffrey Hsu <email>hsu@FreeBSD.org</email>">
<!ENTITY a.imp "Warner Losh <email>imp@FreeBSD.org</email>">
<!ENTITY a.itojun "Jun-ichiro Itoh <email>itojun@itojun.org</email>">
<!ENTITY a.iwasaki "Mitsuru IWASAKI <email>iwasaki@FreeBSD.org</email>">
<!ENTITY a.jasone "Jason Evans <email>jasone@FreeBSD.org</email>">
<!ENTITY a.jb "John Birrell <email>jb@cimlogic.com.au</email>">
<!ENTITY a.jdp "John Polstra <email>jdp@FreeBSD.org</email>">
<!ENTITY a.jehamby "Jake Hamby <email>jehamby@lightside.com</email>">
<!ENTITY a.jfieber "John Fieber <email>jfieber@FreeBSD.org</email>">
<!ENTITY a.jfitz "James FitzGibbon <email>jfitz@FreeBSD.org</email>">
<!ENTITY a.jgreco "Joe Greco <email>jgreco@FreeBSD.org</email>">
<!ENTITY a.jhay "John Hay <email>jhay@FreeBSD.org</email>">
<!ENTITY a.jhs "Julian Stacey <email>jhs@FreeBSD.org</email>">
<!ENTITY a.jim "Jim Mock <email>jim@FreeBSD.org</email>">
<!ENTITY a.jkh "Jordan K. Hubbard <email>jkh@FreeBSD.org</email>">
<!ENTITY a.jkoshy "Joseph Koshy <email>jkoshy@FreeBSD.org</email>">
<!ENTITY a.jlemon "Jonathan Lemon <email>jlemon@FreeBSD.org</email>">
<!ENTITY a.jlind "John Lind <email>john@starfire.MN.ORG</email>">
<!ENTITY a.jlrobin "James L. Robinson <email>jlrobin@FreeBSD.org</email>">
<!ENTITY a.jmacd "Joshua Peck Macdonald <email>jmacd@FreeBSD.org</email>">
<!ENTITY a.jmb "Jonathan M. Bresler <email>jmb@FreeBSD.org</email>">
<!ENTITY a.jmg "John-Mark Gurney <email>jmg@FreeBSD.org</email>">
<!ENTITY a.jmz "Jean-Marc Zucconi <email>jmz@FreeBSD.org</email>">
<!ENTITY a.joerg "J&ouml;rg Wunsch <email>joerg@FreeBSD.org</email>">
<!ENTITY a.john "John Cavanaugh <email>john@FreeBSD.org</email>">
<!ENTITY a.jraynard "James Raynard <email>jraynard@FreeBSD.org</email>">
<!ENTITY a.jseger "Justin Seger <email>jseger@FreeBSD.org</email>">
<!ENTITY a.julian "Julian Elischer <email>julian@FreeBSD.org</email>">
<!ENTITY a.jvh "Johannes Helander <email>jvh@FreeBSD.org</email>">
<!ENTITY a.karl "Karl Strickland <email>karl@FreeBSD.org</email>">
<!ENTITY a.kato "Takenori KATO <email>kato@FreeBSD.org</email>">
<!ENTITY a.kelly "Sean Kelly <email>kelly@plutotech.com</email>">
<!ENTITY a.ken "Kenneth D. Merry <email>ken@FreeBSD.org</email>">
<!ENTITY a.kevlo "Kevin Lo <email>kevlo@FreeBSD.org</email>">
<!ENTITY a.kjc "Kenjiro Cho <email>kjc@FreeBSD.org</email>">
<!ENTITY a.kris "Kris Kennaway <email>kris@FreeBSD.org</email>">
<!ENTITY a.kuriyama "Jun Kuriyama <email>kuriyama@FreeBSD.org</email>">
<!ENTITY a.lars "Lars Fredriksen <email>lars@FreeBSD.org</email>">
<!ENTITY a.lile "Larry Lile <email>lile@FreeBSD.org</email>">
<!ENTITY a.ljo "L Jonas Olsson <email>ljo@FreeBSD.org</email>">
<!ENTITY a.luoqi "Luoqi Chen <email>luoqi@FreeBSD.org</email>">
<!ENTITY a.marcel "Marcel Moolenaar <email>marcel@FreeBSD.org</email>">
<!ENTITY a.markm "Mark Murray <email>markm@FreeBSD.org</email>">
<!ENTITY a.martin "Martin Renters <email>martin@FreeBSD.org</email>">
<!ENTITY a.max "Masafumi NAKANE <email>max@FreeBSD.org</email>">
<!ENTITY a.mayo "Mark Mayo <email>mark@vmunix.com</email>">
<!ENTITY a.mbarkah "Ade Barkah <email>mbarkah@FreeBSD.org</email>">
<!ENTITY a.mckay "Stephen McKay <email>mckay@FreeBSD.org</email>">
<!ENTITY a.mckusick "Kirk McKusick <email>mckusick@FreeBSD.org</email>">
<!ENTITY a.md "Mark Dapoz <email>md@bsc.no</email>">
<!ENTITY a.mdodd "Matthew N. Dodd <email>winter@jurai.net</email>">
<!ENTITY a.mharo "Michael Haro <email>mharo@FreeBSD.org</email>">
<!ENTITY a.mjacob "Matthew Jacob <email>mjacob@FreeBSD.org</email>">
<!ENTITY a.mks "Mike Spengler <email>mks@FreeBSD.org</email>">
<!ENTITY a.motoyuki "Motoyuki Konno <email>motoyuki@FreeBSD.org</email>">
<!ENTITY a.mph "Matthew Hunt <email>mph@FreeBSD.org</email>">
<!ENTITY a.mpp "Mike Pritchard <email>mpp@FreeBSD.org</email>">
<!ENTITY a.msmith "Michael Smith <email>msmith@FreeBSD.org</email>">
<!ENTITY a.nate "Nate Williams <email>nate@FreeBSD.org</email>">
<!ENTITY a.nectar "Jacques Vidrine <email>nectar@FreeBSD.org</email>">
<!ENTITY a.newton "Mark Newton <email>newton@FreeBSD.org</email>">
<!ENTITY a.nhibma "Nick Hibma <email>n_hibma@FreeBSD.org</email>">
<!ENTITY a.nik "Nik Clayton <email>nik@FreeBSD.org</email>">
<!ENTITY a.nsayer "Nick Sayer <email>nsayer@FreeBSD.org</email>">
<!ENTITY a.nsj "Nate Johnson <email>nsj@FreeBSD.org</email>">
<!ENTITY a.nyan "Yoshihiro Takahashi <email>nyan@FreeBSD.org</email>">
<!ENTITY a.obrien "David O'Brien <email>obrien@FreeBSD.org</email>">
<!ENTITY a.olah "Andras Olah <email>olah@FreeBSD.org</email>">
<!ENTITY a.opsys "Chris Watson <email>opsys@open-systems.net</email>">
<!ENTITY a.paul "Paul Richards <email>paul@FreeBSD.org</email>">
<!ENTITY a.pb "Pierre Beyssac <email>pb@fasterix.freenix.org</email>">
<!ENTITY a.pds "Peter da Silva <email>pds@FreeBSD.org</email>">
<!ENTITY a.peter "Peter Wemm <email>peter@FreeBSD.org</email>">
<!ENTITY a.phk "Poul-Henning Kamp <email>phk@FreeBSD.org</email>">
<!ENTITY a.pjc "Peter Childs <email>pjchilds@imforei.apana.org.au</email>">
<!ENTITY a.proven "Chris Provenzano <email>proven@FreeBSD.org</email>">
<!ENTITY a.pst "Paul Traina <email>pst@FreeBSD.org</email>">
<!ENTITY a.rgrimes "Rodney Grimes <email>rgrimes@FreeBSD.org</email>">
<!ENTITY a.rhuff "Robert Huff <email>rhuff@cybercom.net</email>">
<!ENTITY a.ricardag "Ricardo AG <email>ricardag@ag.com.br</email>">
<!ENTITY a.rich "Rich Murphey <email>rich@FreeBSD.org</email>">
<!ENTITY a.rnordier "Robert Nordier <email>rnordier@FreeBSD.org</email>">
<!ENTITY a.roberto "Ollivier Robert <email>roberto@FreeBSD.org</email>">
<!ENTITY a.rse "Ralf S. Engelschall <email>rse@FreeBSD.org</email>">
<!ENTITY a.ru "Ruslan Ermilov <email>ru@FreeBSD.org</email>">
<!ENTITY a.sada "Kenji SADA <email>sada@FreeBSD.org</email>">
<!ENTITY a.scrappy "Marc G. Fournier <email>scrappy@FreeBSD.org</email>">
<!ENTITY a.se "Stefan Esser <email>se@FreeBSD.org</email>">
<!ENTITY a.sef "Sean Eric Fagan <email>sef@FreeBSD.org</email>">
<!ENTITY a.sheldonh "Sheldon Hearn <email>sheldonh@FreeBSD.org</email>">
<!ENTITY a.shige "Shigeyuki Fukushima <email>shige@FreeBSD.org</email>">
<!ENTITY a.shin "Yoshinobu Inoue <email>shin@FreeBSD.org</email>">
<!ENTITY a.simokawa "Hidetoshi Shimokawa <email>simokawa@FreeBSD.org</email>">
<!ENTITY a.smace "Scott Mace <email>smace@FreeBSD.org</email>">
<!ENTITY a.smpatel "Sujal Patel <email>smpatel@FreeBSD.org</email>">
<!ENTITY a.sos "S&oslash;ren Schmidt <email>sos@FreeBSD.org</email>">
<!ENTITY a.stark "Gene Stark <email>stark@FreeBSD.org</email>">
<!ENTITY a.stb "Stefan Bethke <email>stb@FreeBSD.org</email>">
<!ENTITY a.steve "Steve Price <email>steve@FreeBSD.org</email>">
<!ENTITY a.sumikawa "Munechika Sumikawa <email>sumikawa@FreeBSD.org</email>">
<!ENTITY a.swallace "Steven Wallace <email>swallace@FreeBSD.org</email>">
<!ENTITY a.tanimura "Seigo Tanimura <email>tanimura@FreeBSD.org</email>">
<!ENTITY a.taoka "Satoshi Taoka <email>taoka@FreeBSD.org</email>">
<!ENTITY a.tedm "Ted Mittelstaedt <email>tedm@FreeBSD.org</email>">
<!ENTITY a.tegge "Tor Egge <email>tegge@FreeBSD.org</email>">
<!ENTITY a.tg "Thomas Gellekum <email>tg@FreeBSD.org</email>">
<!ENTITY a.thepish "Peter Hawkins <email>thepish@FreeBSD.org</email>">
<!ENTITY a.tom "Tom Hukins <email>tom@FreeBSD.org</email>">
<!ENTITY a.torstenb "Torsten Blum <email>torstenb@FreeBSD.org</email>">
<!ENTITY a.truckman "Don &ldquo;Truck&rdquo; Lewis <email>truckman@FreeBSD.org</email>">
<!ENTITY a.ugen "Ugen J.S.Antsilevich <email>ugen@FreeBSD.org</email>">
<!ENTITY a.uhclem "Frank Durda IV <email>uhclem@FreeBSD.org</email>">
<!ENTITY a.ulf "Ulf Zimmermann <email>ulf@FreeBSD.org</email>">
<!ENTITY a.vanilla "Vanilla I. Shu <email>vanilla@FreeBSD.org</email>">
<!ENTITY a.wes "Wes Peters <email>wes@FreeBSD.org</email>">
<!ENTITY a.whiteside "Don Whiteside <email>whiteside@acm.org</email>">
<!ENTITY a.wilko "Wilko Bulte <email>wilko@yedi.iaf.nl</email>">
<!ENTITY a.wlloyd "Bill Lloyd <email>wlloyd@mpd.ca</email>">
<!ENTITY a.wollman "Garrett Wollman <email>wollman@FreeBSD.org</email>">
<!ENTITY a.wosch "Wolfram Schneider <email>wosch@FreeBSD.org</email>">
<!ENTITY a.wpaul "Bill Paul <email>wpaul@FreeBSD.org</email>">
<!ENTITY a.yokota "Kazutaka YOKOTA <email>yokota@FreeBSD.org</email>">

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

@ -1,621 +0,0 @@
<!--
The FreeBSD Documentation Project
$Id: chapter.sgml,v 1.8 1999-06-15 20:37:38 mpp Exp $
-->
<chapter id="backups">
<title>Backups</title>
<para>Issues of hardware compatibility are among the most troublesome in the
computer industry today and FreeBSD is by no means immune to trouble. In
this respect, FreeBSD's advantage of being able to run on inexpensive
commodity PC hardware is also its liability when it comes to support for
the amazing variety of components on the market. While it would be
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>
<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
catalog. If you have direct experience of hardware that does or does not
work with FreeBSD, please let us know by sending e-mail to the &a.doc;.
Questions about supported hardware should be directed to the &a.questions
(see <link linkend="eresources-mail">Mailing Lists</link> for more
information). When submitting information or asking a question, please
remember to specify exactly what version of FreeBSD you are using and
include as many details of your hardware as possible.</para>
<sect1>
<title>* What about backups to floppies?</title>
<para></para>
</sect1>
<sect1 id="backups-tapebackups">
<title>Tape Media</title>
<para>The major tape media are the 4mm, 8mm, QIC, mini-cartridge and
DLT.</para>
<sect2 id="backups-tapebackups-4mm">
<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,
a leading manufacturer of QIC drives, and then stopped production of
QIC drives. 4mm drives are small and quiet but do not have the
reputation for reliability that is enjoyed by 8mm drives. The
cartridges are less expensive and smaller (3 x 2 x 0.5 inches, 76 x 51
x 12 mm) than 8mm cartridges. 4mm, like 8mm, has comparatively short
head life for the same reason, both use helical scan.</para>
<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>
<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>
<para>Tapes should be retired from use after 2,000 passes or 100 full
backups.</para>
</sect2>
<sect2 id="backups-tapebackups-8mm">
<title>8mm (Exabyte)</title>
<para>8mm tapes are the most common SCSI tape drives; they are the best
choice of exchanging tapes. Nearly every site has an exabyte 2 GB 8mm
tape drive. 8mm drives are reliable, convenient and quiet. Cartridges
are inexpensive and small (4.8 x 3.3 x 0.6 inches; 122 x 84 x 15 mm).
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 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>
</sect2>
<sect2 id="backups-tapebackups-qic">
<title>QIC</title>
<para>QIC-150 tapes and drives are, perhaps, the most common tape drive
and media around. QIC tape drives are the least expensive "serious"
backup drives. The downside is the cost of media. QIC tapes are
expensive compared to 8mm or 4mm tapes, up to 5 times the price per GB
data storage. But, if your needs can be satisfied with a half-dozen
tapes, QIC may be the correct choice. QIC is the
<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>
<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
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
and more robust than for helical scan drives).</para>
<para>Tapes should be retired from use after 5,000 backups.</para>
</sect2>
<sect2 id="backups-tapebackups-mini">
<title>* Mini-Cartridge</title>
<para></para>
</sect2>
<sect2 id="backups-tapebackups-dlt">
<title>DLT</title>
<para>DLT has the fastest data transfer rate of all the drive types
listed here. The 1/2" (12.5mm) tape is contained in a single spool
cartridge (4 x 4 x 1 inches; 100 x 100 x 25 mm). The cartridge has a
swinging gate along one entire side of the cartridge. The drive
mechanism opens this gate to extract the tape leader. The tape leader
has an oval hole in it which the drive uses to "hook" the tape. The
take-up spool is located inside the tape drive. All the other tape
cartridges listed here (9 track tapes are the only exception) have
both the supply and take-up spools located inside the tape cartridge
itself.</para>
<para>Data thruput is approximately 1.5MB/s, three times the thruput of
4mm, 8mm, or QIC tape drives. Data capacities range from 10GB to 20GB
for a single drive. Drives are available in both multi-tape changers
and multi-tape, multi-drive tape libraries containing from 5 to 900
tapes over 1 to 20 drives, providing from 50GB to 9TB of
storage.</para>
<para>Data is recorded onto the tape in tracks parallel to the direction
of travel (just like QIC tapes). Two tracks are written at once.
Read/write head lifetimes are relatively long; once the tape stops
moving, there is no relative motion between the heads and the
tape.</para>
</sect2>
<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>
<screen>sa0(ncr1:4:0): NOT READY asc:4,1
sa0(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>
<para><command>mt fsf 1</command> causes the tape drive to write an
Identifier Block to the tape.</para>
<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>&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>
<para>Subsequent tape operations are successful.</para>
</sect2>
</sect1>
<sect1 id="backup-programs">
<title>Backup Programs</title>
<para>The three major programs are
&man.dump.8;,
&man.tar.1;,
and
&man.cpio.1;.</para>
<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.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/nrsa8 /dev/rda0a 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>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/nrsa8 . 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 through <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>
</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>
</sect2>
<sect2 id="backups-programs-amanda">
<title>Amanda</title>
<para><ulink url="../ports/misc.html#amanda-2.4.0">Amanda</ulink>
(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
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
create full backups of all the filesystems listed in Amanda's
configuration file. The "archive set" also contains nightly
incremental (or differential) backups of all the filesystems.
Restoring a damaged filesystem requires the most recent full backup
and the incremental backups.</para>
<para>The configuration file provides fine control backups and the
network traffic that Amanda generates. Amanda will use any of the
above backup programs to write the data to tape. Amanda is available
as either a port or a package, it is not installed by default.</para>
</sect2>
<sect2>
<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>
<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
computer. But beware, Unix is a useful tool, you may find that within
six months you have a collection of files that are valuable to
you.</para>
<para>&ldquo;Do nothing&rdquo; is the correct backup method for
<filename>/usr/obj</filename> and other directory trees that can be
exactly recreated by your computer. An example is the files that
comprise these handbook pages-they have been generated from
<acronym>SGML</acronym> input files. Creating backups of these
<acronym>HTML</acronym> files is not necessary. The
<acronym>SGML</acronym> source files are backed up regularly.</para>
</sect2>
<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>
</sect2>
<sect2>
<title>Emergency Restore Procedure</title>
<sect3>
<title>Before the Disaster</title>
<para>There are only four steps that you need to perform in
preparation for any disaster that may occur.</para>
<para>First, print the disklabel from each of your disks
(<command>e.g. disklabel da0 | lpr</command>), your filesystem table
(<command>/etc/fstab</command>) and all boot messages, two copies of
each.</para>
<para>Second, determine that the boot and fixit floppies
(<filename>boot.flp</filename> and <filename>fixit.flp</filename>)
have all your devices. The easiest way to check is to reboot your
machine with the boot floppy in the floppy drive and check the boot
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
&man.restore.8;.</para>
<para>Third, create backup tapes regularly. Any changes that you make
after your last backup may be irretrievably lost. Write-protect the
backup tapes.</para>
<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/rsa0</command>, you
might accidently type <command>tar cvf /dev/rsa0</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>
<para>An example script for creating a bootable floppy:</para>
<programlisting>
<![ CDATA [#!/bin/sh
#
# create a restore floppy
#
# format the floppy
#
PATH=/bin:/sbin:/usr/sbin:/usr/bin
fdformat -q fd0
if [ $? -ne 0 ]
then
echo "Bad floppy, please use a new one"
exit 1
fi
# place boot blocks on the floppy
#
disklabel -w -B /dev/rfd0c fd1440
#
# newfs the one and only partition
#
newfs -t 2 -u 18 -l 1 -c 40 -i 5120 -m 5 -o space /dev/rfd0a
#
# mount the new floppy
#
mount /dev/fd0a /mnt
#
# create required directories
#
mkdir /mnt/dev
mkdir /mnt/bin
mkdir /mnt/sbin
mkdir /mnt/etc
mkdir /mnt/root
mkdir /mnt/mnt # for the root partition
mkdir /mnt/tmp
mkdir /mnt/var
#
# populate the directories
#
if [ ! -x /sys/compile/MINI/kernel ]
then
cat << EOM
The MINI kernel does not exist, please create one.
Here is an example config file:
#
# MINI -- A kernel to get FreeBSD on onto a disk.
#
machine "i386"
cpu "I486_CPU"
ident MINI
maxusers 5
options INET # needed for _tcp _icmpstat _ipstat
# _udpstat _tcpstat _udb
options FFS #Berkeley Fast File System
options FAT_CURSOR #block cursor in syscons or pccons
options SCSI_DELAY=15 #Be pessimistic about Joe SCSI device
options NCONS=2 #1 virtual consoles
options USERCONFIG #Allow user configuration with -c XXX
config kernel root on da0 swap on da0 and da1 dumps on da0
controller isa0
controller pci0
controller fdc0 at isa? port "IO_FD1" bio irq 6 drq 2 vector fdintr
disk fd0 at fdc0 drive 0
controller ncr0
controller scbus0
device sc0 at isa? port "IO_KBD" tty irq 1 vector scintr
device npx0 at isa? port "IO_NPX" irq 13 vector npxintr
device da0
device da1
device da2
device sa0
pseudo-device loop # required by INET
pseudo-device gzip # Exec gzipped a.out's
EOM
exit 1
fi
cp -f /sys/compile/MINI/kernel /mnt
gzip -c -best /sbin/init > /mnt/sbin/init
gzip -c -best /sbin/fsck > /mnt/sbin/fsck
gzip -c -best /sbin/mount > /mnt/sbin/mount
gzip -c -best /sbin/halt > /mnt/sbin/halt
gzip -c -best /sbin/restore > /mnt/sbin/restore
gzip -c -best /bin/sh > /mnt/bin/sh
gzip -c -best /bin/sync > /mnt/bin/sync
cp /root/.profile /mnt/root
cp -f /dev/MAKEDEV /mnt/dev
chmod 755 /mnt/dev/MAKEDEV
chmod 500 /mnt/sbin/init
chmod 555 /mnt/sbin/fsck /mnt/sbin/mount /mnt/sbin/halt
chmod 555 /mnt/bin/sh /mnt/bin/sync
chmod 6555 /mnt/sbin/restore
#
# create the devices nodes
#
cd /mnt/dev
./MAKEDEV std
./MAKEDEV da0
./MAKEDEV da1
./MAKEDEV da2
./MAKEDEV sa0
./MAKEDEV pty0
cd /
#
# create minimum filesystem table
#
cat > /mnt/etc/fstab <<EOM
/dev/fd0a / ufs rw 1 1
EOM
#
# create minimum passwd file
#
cat > /mnt/etc/passwd <<EOM
root:*:0:0:Charlie &:/root:/bin/sh
EOM
cat > /mnt/etc/master.passwd <<EOM
root::0:0::0:0:Charlie &:/root:/bin/sh
EOM
chmod 600 /mnt/etc/master.passwd
chmod 644 /mnt/etc/passwd
/usr/sbin/pwd_mkdb -d/mnt/etc /mnt/etc/master.passwd
#
# umount the floppy and inform the user
#
/sbin/umount /mnt]]></programlisting>
</sect3>
<sect3>
<title>After the Disaster</title>
<para>The key question is: did your hardware survive? You have been
doing regular backups so there is no need to worry about the
software.</para>
<para>If the hardware has been damaged. First, replace those parts
that have been damaged.</para>
<para>If your hardware is okay, check your floppies. If you are using
a custom boot floppy, boot single-user (type <literal>-s</literal>
at the <prompt>boot:</prompt> prompt). Skip the following
paragraph.</para>
<para>If you are using the <filename>boot.flp</filename> and
<filename>fixit.flp</filename> floppies, keep reading. Insert the
<filename>boot.flp</filename> floppy in the first floppy drive and
boot the computer. The original install menu will be displayed on
the screen. Select the <literal>Fixit--Repair mode with CDROM or
floppy.</literal> option. Insert the
<filename>fixit.flp</filename> when prompted.
<command>restore</command> and the other programs that you need are
located in <filename>/mnt2/stand</filename>.</para>
<para>Recover each filesystem separately.</para>
<para>Try to &man.mount.8; (e.g. <command>mount /dev/da0a
/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/sa0</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
hour spent now, may save you from further distress later.</para>
</sect3>
<sect3>
<title>* I did not prepare for the Disaster, What Now?</title>
<para></para>
</sect3>
</sect2>
</sect1>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->

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

@ -1,139 +0,0 @@
<!--
The FreeBSD Documentation Project
$Id: chapter.sgml,v 1.9 1999-04-08 21:30:16 nik Exp $
-->
<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>
<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>
<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>
<listitem>
<para>System calls and error numbers</para>
</listitem>
<listitem>
<para>Functions in the C libraries</para>
</listitem>
<listitem>
<para>Device drivers</para>
</listitem>
<listitem>
<para>File formats</para>
</listitem>
<listitem>
<para>Games and other diversions</para>
</listitem>
<listitem>
<para>Miscellaneous information</para>
</listitem>
<listitem>
<para>System maintenance and operation commands</para>
</listitem>
<listitem>
<para>Kernel developers</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>
<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
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>
<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>
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>
</sect1>
<sect1 id="basics-info">
<title>GNU Info Files</title>
<para>FreeBSD includes many applications and utilities produced by the
Free Software Foundation (FSF). In addition to man pages, these
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>
<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>
</sect1>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->

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

@ -1,478 +0,0 @@
<!--
The FreeBSD Documentation Project
$Id: chapter.sgml,v 1.13 1999-08-05 20:48:08 nik Exp $
-->
<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>
<sect1>
<title>Books &amp; Magazines Specific to FreeBSD</title>
<para><emphasis>International books &amp;
Magazines:</emphasis></para>
<itemizedlist>
<listitem>
<para><ulink
URL="http://freebsd.csie.nctu.edu.tw/~jdli/book.html">Using
FreeBSD</ulink> (in Chinese).</para>
</listitem>
<listitem>
<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>
</listitem>
<listitem>
<para><ulink
URL="http://www.shoeisha.co.jp/pc/index/shinkan/97_05_06.htm">Complete Introduction to FreeBSD</ulink> (in Japanese), published by <ulink URL="http://www.shoeisha.co.jp/">Shoeisha Co., Ltd</ulink>. ISBN 4-88135-473-6 P3600E.</para>
</listitem>
<listitem>
<para><ulink
URL="http://www.ascii.co.jp/pb/book1/shinkan/detail/1322785.html">Personal UNIX Starter Kit FreeBSD</ulink> (in Japanese), published by <ulink URL="http://www.ascii.co.jp/">ASCII</ulink>. ISBN 4-7561-1733-3 P3000E.</para>
</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>
</listitem>
<listitem>
<para>FreeBSD mit Methode (in German), published by Computer und
Literatur Verlag/Vertrieb Hanser, 1998. ISBN 3-932311-31-0.</para>
</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>
</listitem>
</itemizedlist>
<para><emphasis>English language books &amp; Magazines:</emphasis></para>
<itemizedlist>
<listitem>
<para><ulink
URL="http://www.cdrom.com/titles/freebsd/bsdbook2.phtml">The
Complete FreeBSD</ulink>, published by <ulink
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. 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. ISBN 1-56592-076-7</para>
</listitem>
<listitem>
<para><emphasis>UNIX in a Nutshell</emphasis>. O'Reilly &amp;
Associates, Inc., 1990. 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. 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>
</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>
</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.
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. ISBN 1-56592-080-5</para>
</listitem>
<listitem>
<para>Costales, Brian, et al. <emphasis>Sendmail</emphasis>, 2nd Ed.
O'Reilly &amp; Associates, Inc., 1997. 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. ISBN 1-56592-127-5</para>
</listitem>
<listitem>
<para>Hunt, Craig. <emphasis>TCP/IP Network
Administration</emphasis>. O'Reilly &amp; Associates, Inc., 1992.
ISBN 0-937175-82-X</para>
</listitem>
<listitem>
<para>Nemeth, Evi. <emphasis>UNIX System Administration
Handbook</emphasis>. 2nd Ed. Prentice Hall, 1995. ISBN
0131510517</para>
</listitem>
<listitem>
<para>Stern, Hal <emphasis>Managing NFS and NIS</emphasis> O'Reilly
&amp; Associates, Inc., 1991. 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>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>Programmers' Guides</title>
<itemizedlist>
<listitem>
<para>Asente, Paul. <emphasis>X Window System Toolkit</emphasis>.
Digital Press. 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. 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. 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.
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.
ISBN 0-13-110362-9</para>
</listitem>
<listitem>
<para>Lehey, Greg. <emphasis>Porting UNIX Software</emphasis>.
O'Reilly &amp; Associates, Inc., 1995. ISBN 1-56592-126-7</para>
</listitem>
<listitem>
<para>Plauger, P. J. <emphasis>The Standard C Library</emphasis>.
Prentice Hall, 1992. 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
ISBN 0-201-56317-7</para>
</listitem>
<listitem>
<para>Stevens, W. Richard. <emphasis>UNIX Network
Programming</emphasis>. 2nd Ed, PTR Prentice Hall, 1998. ISBN
0-13-490012-X</para>
</listitem>
<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>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>Operating System Internals</title>
<itemizedlist>
<listitem>
<para>Andleigh, Prabhat K. <emphasis>UNIX System
Architecture</emphasis>. Prentice-Hall, Inc., 1990. 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>
</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. 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. 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. :
Addison-Wesley, 1996. 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. 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>
</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.
ISBN 0-201-63495-3</para>
</listitem>
<listitem>
<para>Vahalia, Uresh. <emphasis>UNIX Internals -- The New
Frontiers</emphasis>. Prentice Hall, 1996. ISBN
0-13-101908-2</para>
</listitem>
<listitem>
<para>Wright, Gary R. and W. Richard Stevens. <emphasis>TCP/IP
Illustrated, Volume 2: The Implementation</emphasis>. Reading,
Mass. : Addison-Wesley, 1995. 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. 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. ISBN 1-56592-148-8</para>
</listitem>
<listitem>
<para>Garfinkel, Simson. <emphasis>PGP Pretty Good
Privacy</emphasis> O'Reilly &amp; Associates, Inc., 1995. 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. :
Addison-Wesley, 1995. ISBN 0-201-40992-5</para>
</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. ISBN 0-201-62490-7</para>
</listitem>
<listitem>
<para>Intel Corporation publishes documentation on their CPUs,
chipsets and standards on their <ulink
url="http://developer.intel.com/">developer web site</ulink>,
usually as PDF files.</para>
</listitem>
<listitem>
<para>Shanley, Tom. <emphasis>80486 System Architecture</emphasis>.
3rd ed. Reading, Mass. : Addison-Wesley, 1995. ISBN
0-201-40994-1</para>
</listitem>
<listitem>
<para>Shanley, Tom. <emphasis>ISA System Architecture</emphasis>.
3rd ed. Reading, Mass. : Addison-Wesley, 1995. ISBN
0-201-40996-8</para>
</listitem>
<listitem>
<para>Shanley, Tom. <emphasis>PCI System Architecture</emphasis>.
3rd ed. Reading, Mass. : Addison-Wesley, 1995. ISBN
0-201-40993-3</para>
</listitem>
<listitem>
<para>Van Gilluwe, Frank. <emphasis>The Undocumented PC</emphasis>.
Reading, Mass: Addison-Wesley Pub. Co., 1994. 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. ISBN
1573980137</para>
</listitem>
<listitem>
<para>Raymond, Eric S. <emphasis>The New Hacker's Dictionary, 3rd
edition</emphasis>. MIT Press, 1996. ISBN
0-262-68092-0. Also known as the <ulink
URL="http://www.ccil.org/jargon/jargon.html">Jargon
File</ulink></para>
</listitem>
<listitem>
<para>Salus, Peter H. <emphasis>A quarter century of UNIX</emphasis>.
Addison-Wesley Publishing Company, Inc., 1994. 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. 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. ISBN
0-13-536657-7</para>
</listitem>
<listitem>
<para><emphasis>The BSD family tree</emphasis>. 1997. <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. <ulink
URL="http://www.de.FreeBSD.org/de/ftp/releases/">http://www.de.FreeBSD.org/de/ftp/releases/</ulink></para>
</listitem>
<listitem>
<para><emphasis>Networked Computer Science Technical Reports
Library</emphasis>. <ulink
URL="http://www.ncstrl.org/">http://www.ncstrl.org/</ulink></para>
</listitem>
<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>
</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>
</listitem>
<listitem>
<para><emphasis>Sys Admin &mdash; The Journal for UNIX System
Administrators</emphasis> Miller Freeman, Inc., ISSN
1061-2688</para>
</listitem>
</itemizedlist>
</sect1>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->

1
en/handbook/chapter.decl
View file

@ -1 +0,0 @@
<!DOCTYPE chapter PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN">

49
en/handbook/chapters.ent
View file

@ -1,49 +0,0 @@
<!--
Creates entities for each chapter in the FreeBSD Handbook. Each entity
is named chap.foo, where foo is the value of the id attribute on that
chapter, and corresponds to the name of the directory in which that
chapter's .sgml file is stored.
Chapters should be listed in the order in which they are referenced.
$Id: chapters.ent,v 1.3 1998-11-12 01:26:17 nik Exp $
-->
<!-- Part one -->
<!ENTITY chap.introduction SYSTEM "introduction/chapter.sgml">
<!ENTITY chap.install SYSTEM "install/chapter.sgml">
<!ENTITY chap.basics SYSTEM "basics/chapter.sgml">
<!ENTITY chap.ports SYSTEM "ports/chapter.sgml">
<!-- Part two -->
<!ENTITY chap.kernelconfig SYSTEM "kernelconfig/chapter.sgml">
<!ENTITY chap.security SYSTEM "security/chapter.sgml">
<!ENTITY chap.printing SYSTEM "printing/chapter.sgml">
<!ENTITY chap.disks SYSTEM "disks/chapter.sgml">
<!ENTITY chap.backups SYSTEM "backups/chapter.sgml">
<!ENTITY chap.quotas SYSTEM "quotas/chapter.sgml">
<!ENTITY chap.x11 SYSTEM "x11/chapter.sgml">
<!ENTITY chap.hw SYSTEM "hw/chapter.sgml">
<!ENTITY chap.l10n SYSTEM "l10n/chapter.sgml">
<!-- Part three -->
<!ENTITY chap.serialcomms SYSTEM "serialcomms/chapter.sgml">
<!ENTITY chap.ppp-and-slip SYSTEM "ppp-and-slip/chapter.sgml">
<!ENTITY chap.advanced-networking SYSTEM "advanced-networking/chapter.sgml">
<!ENTITY chap.mail SYSTEM "mail/chapter.sgml">
<!-- Part four -->
<!ENTITY chap.cutting-edge SYSTEM "cutting-edge/chapter.sgml">
<!ENTITY chap.contrib SYSTEM "contrib/chapter.sgml">
<!ENTITY chap.policies SYSTEM "policies/chapter.sgml">
<!ENTITY chap.kernelopts SYSTEM "kernelopts/chapter.sgml">
<!ENTITY chap.kerneldebug SYSTEM "kerneldebug/chapter.sgml">
<!ENTITY chap.linuxemu SYSTEM "linuxemu/chapter.sgml">
<!ENTITY chap.internals SYSTEM "internals/chapter.sgml">
<!-- Part five (appendices) -->
<!ENTITY chap.mirrors SYSTEM "mirrors/chapter.sgml">
<!ENTITY chap.bibliography SYSTEM "bibliography/chapter.sgml">
<!ENTITY chap.eresources SYSTEM "eresources/chapter.sgml">
<!ENTITY chap.staff SYSTEM "staff/chapter.sgml">
<!ENTITY chap.pgpkeys SYSTEM "pgpkeys/chapter.sgml">

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

File diff suppressed because it is too large Load diff

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

File diff suppressed because it is too large Load diff

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

@ -1,168 +0,0 @@
<!--
The FreeBSD Documentation Project
$Id: chapter.sgml,v 1.6 1999-05-16 13:40:15 nik Exp $
-->
<chapter id="disks">
<title>Disks</title>
<para><emphasis>Contributed by &a.obrien; 26 April 1998</emphasis></para>
<para>Lets say we want to add a new SCSI disk to a machine that currently
only has a single drive. First turn off the computer and install the
drive in the computer following the instructions of the computer,
controller, and drive manufacturer. Due the wide variations of procedures
to do this, the details are beyond the scope of this document.</para>
<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>da1</filename> and we want to mount it on
<filename>/1</filename>. (if you are adding an IDE drive substitute
<filename>wd</filename> for <filename>da</filename>)</para>
<para>Because FreeBSD runs on IBM-PC compatible computers, it must take into
account the PC BIOS partitions. These are different from the traditional
BSD partitions. A PC disk has up to four BIOS partition entries. If the
disk is going to be truly dedicated to FreeBSD, you can use the
<emphasis>dedicated</emphasis> mode. Otherwise, FreeBSD will have to live
with in one of the PC BIOS partitions. FreeBSD calls the PC BIOS
partitions, <emphasis>slices</emphasis> so as not to confuse them with
traditional BSD partitions. You may also use slices on a disk that is
dedicated to FreeBSD, but used in a computer that also has another
operating system installed. This is to not confuse the
<command>fdisk</command> utility of the other operating system.</para>
<para>In the slice case the drive will be added as
<filename>/dev/da1s1e</filename>. This is read as: SCSI disk, unit number
1 (second SCSI disk), slice 1 (PC BIOS partition 1), and
<filename>e</filename> BSD partition. In the dedicated case, the drive
will be added simply as <filename>/dev/da1e</filename>.</para>
<sect1>
<title>Using sysinstall</title>
<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
<literal>Configure</literal> menu. With in the <literal>FreeBSD
Configuration Menu</literal>, scroll down and select the
<literal>Partition</literal> item. Next you should be presented with a
list of hard drives installed in your system. If you do not see
<literal>da1</literal> listed, you need to recheck your physical
installation and <command>dmesg</command> output in the file
<filename>/var/run/dmesg.boot</filename>.</para>
<para>Select <literal>da1</literal> to enter the <literal>FDISK Partition
Editor</literal>. Choose <literal>A</literal> to use the entire disk
for FreeBSD. When asked if you want to <quote>remain cooperative with
any future possible operating systems</quote>, answer
<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>
<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>
<para>Sysinstall's Label editor favors the <literal>e</literal> partition
for non-root, non-swap partitions. With in the Label editor, create a
single file system using <command>C</command>. When prompted if this
will be a FS (file system) or swap, choose <literal>FS</literal> and
give a mount point (e.g, <filename>/mnt</filename>). When adding a disk
in post-install mode, Sysinstall will not create entries in
<filename>/etc/fstab</filename> for you, so the mount point you specify
isn't important.</para>
<para>You are now ready to write the new label to the disk and create a
file system on it. Do this by hitting <command>W</command>. Ignore any
errors from Sysinstall that it could not mount the new partition. Exit
the Label Editor and Sysinstall completely.</para>
<para>The last step is to edit <filename>/etc/fstab</filename> to add an
entry for your new disk.</para>
</sect1>
<sect1>
<title>Using command line utilities</title>
<sect2>
<title>* Using Slices</title>
<para></para>
</sect2>
<sect2>
<title>Dedicated</title>
<para>If you will not be sharing the new drive with another operating
system, you may use the <literal>dedicated</literal> mode. Remember
this mode can confuse Microsoft operating systems; however, no damage
will be done by them. IBM's OS/2 however, will
&ldquo;appropriate&rdquo; any partition it finds which it doesn't
understand.</para>
<screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/rda1 bs=1k count=1</userinput>
&prompt.root; <userinput>disklabel -Brw da1 auto</userinput>
&prompt.root; <userinput>disklabel -e da1</userinput> # create the `e' partition
&prompt.root; <userinput>newfs -d0 /dev/rda1e</userinput>
&prompt.root; <userinput>mkdir -p /1</userinput>
&prompt.root; <userinput>vi /etc/fstab</userinput> # add an entry for /dev/da1e
&prompt.root; <userinput>mount /1</userinput></screen>
<para>An alternate method is:</para>
<screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/rda1 count=2</userinput>
&prompt.root; <userinput>disklabel /dev/rda1 | disklabel -BrR da1 /dev/stdin</userinput>
&prompt.root; <userinput>newfs /dev/rda1e</userinput>
&prompt.root; <userinput>mkdir -p /1</userinput>
&prompt.root; <userinput>vi /etc/fstab</userinput> # add an entry for /dev/da1e
&prompt.root; <userinput>mount /1</userinput></screen>
</sect2>
</sect1>
<sect1>
<title>* Non-traditional Drives</title>
<sect2>
<title>* Zip Drives</title>
<para></para>
</sect2>
<sect2>
<title>* Jaz Drives</title>
<para></para>
</sect2>
<sect2>
<title>* Sequest Drives</title>
<para></para>
</sect2>
</sect1>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->

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

File diff suppressed because it is too large Load diff

129
en/handbook/handbook.sgml
View file

@ -1,129 +0,0 @@
<!--
The FreeBSD Documentation Project
$Id: handbook.sgml,v 1.78 1999-07-28 20:23:02 nik Exp $
-->
<!DOCTYPE BOOK PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [
<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
%man;
<!ENTITY % bookinfo PUBLIC "-//FreeBSD//ENTITIES DocBook BookInfo Entities//EN">
%bookinfo;
<!ENTITY % chapters SYSTEM "chapters.ent"> %chapters;
<!ENTITY % authors SYSTEM "authors.ent"> %authors;
<!ENTITY % mailing-lists SYSTEM "mailing-lists.ent"> %mailing-lists;
<!ENTITY % newsgroups SYSTEM "newsgroups.ent"> %newsgroups;
<!-- The currently released version of FreeBSD. This value is used to
create some links on web sites and such, so do NOT change it until
it's really release time -->
<!ENTITY rel.current CDATA "3.2">
]>
<book>
<bookinfo>
<title>FreeBSD Handbook</title>
<authorgroup>
<author>
<surname>The FreeBSD Documentation Project</surname>
</author>
</authorgroup>
<pubdate>February 1999</pubdate>
<copyright>
<year>1995</year>
<year>1996</year>
<year>1997</year>
<year>1998</year>
<year>1999</year>
<holder>The FreeBSD Documentation Project</holder>
</copyright>
&bookinfo.legalnotice;
<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
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 a variety of formats and compression
options 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>
</abstract>
</bookinfo>
<part>
<title>Getting Started</title>
&chap.introduction;
&chap.install;
&chap.basics;
&chap.ports
</part>
<part>
<title>System Administration</title>
&chap.kernelconfig;
&chap.security;
&chap.printing;
&chap.disks;
&chap.backups;
&chap.quotas;
&chap.x11;
&chap.hw;
&chap.l10n;
</part>
<part>
<title>Network Communications</title>
&chap.serialcomms;
&chap.ppp-and-slip;
&chap.advanced-networking;
&chap.mail;
</part>
<part>
<title>Advanced topics</title>
&chap.cutting-edge;
&chap.contrib;
&chap.policies;
&chap.kernelopts;
&chap.kerneldebug;
&chap.linuxemu;
&chap.internals;
</part>
<part>
<title>Appendices</title>
&chap.mirrors;
&chap.bibliography;
&chap.eresources;
&chap.staff;
&chap.pgpkeys;
</part>
</book>
<!--
Local Variables:
mode: sgml
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
End:
-->

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

File diff suppressed because it is too large Load diff

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

File diff suppressed because it is too large Load diff

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

File diff suppressed because it is too large Load diff

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

@ -1,607 +0,0 @@
<!--
The FreeBSD Documentation Project
$Id: chapter.sgml,v 1.13 1999-06-13 16:18:55 nik Exp $
-->
<chapter id="introduction">
<title>Introduction</title>
<para>FreeBSD is a 4.4BSD-Lite2 based operating system for Intel architecture
(x86) and DEC Alpha based computer systems. 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 are
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 computer
systems based on both the Intel CPU architecture, which includes the
386 and 486 and Pentium processors (both SX and DX versions) and the DEC
Alpha architecture. Intel compatible CPUs from AMD to 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>
</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>
</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>
</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>
</listitem>
<listitem>
<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>
</listitem>
<listitem>
<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>
</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>
</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>
</listitem>
<listitem>
<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>
</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>
</listitem>
<listitem>
<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-Lite2 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>
<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>
<listitem>
<para>FTP servers</para>
</listitem>
<listitem>
<para>World Wide Web servers</para>
</listitem>
<listitem>
<para>Gopher servers</para>
</listitem>
<listitem>
<para>Electronic Mail servers</para>
</listitem>
<listitem>
<para>USENET News</para>
</listitem>
<listitem>
<para>Bulletin Board Systems</para>
</listitem>
<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>
</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>
</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>
</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>
</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>
</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>
</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>
</sect1>
<sect1 id="history">
<title>A Brief History of FreeBSD</title>
<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>
<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>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>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 November of 1994 to make this
transition, at which point it released FreeBSD 2.0 to the net
and on CDROM (in late December). 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>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>
<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 was released on February
15th, 1999 and 3.2 was released on May 15, 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>
</sect1>
<sect1 id="goals">
<title>FreeBSD Project Goals</title>
<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 are 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 General Public
License (GPL) or Library General Public License (LGPL) 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 when reasonable to do so.</para>
</sect1>
<sect1 id="development">
<title>The FreeBSD Development Model</title>
<para><emphasis>Contributed by &a.asami;</emphasis>.</para>
<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>
<variablelist>
<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
tree</link> section for more information on doing this.</para>
</listitem>
</varlistentry>
<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>
</listitem>
</varlistentry>
<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 whose 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>
<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
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>
</note>
</listitem>
</varlistentry>
<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>
<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
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
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
success!</para>
</sect1>
<sect1 id="relnotes">
<title>About the Current Release</title>
<para>FreeBSD is a freely available, full source 4.4BSD-Lite2 based release
for Intel i386/i486/Pentium/PentiumPro/Pentium II (or compatible) and DEC
Alpha based computer systems. 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 late 94, 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,
ISDN support, support for ATM, 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>In addition to the base distributions, FreeBSD offers a new ported
software collection with hundreds of commonly sought-after programs. At
the end of April 1999 there were more than 2300 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 50MB 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>
<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>
<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>
</sect1>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->

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

File diff suppressed because it is too large Load diff

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

@ -1,597 +0,0 @@
<!--
The FreeBSD Documentation Project
$Id: chapter.sgml,v 1.16 1999-08-05 20:48:16 nik Exp $
-->
<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
<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>
<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>
</note>
<para>When the kernel has been built make a copy of it, say
<filename>kernel.debug</filename>, and then run <command>strip
-g</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>
<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>
<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>Now, after a crash dump, go to
<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>
<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>
3:&prompt.root; <userinput>kgdb kernel /var/crash/vmcore.1</userinput>
4:Reading symbol data from /usr/src/sys/compile/URIAH/kernel
...done.
5:IdlePTD 1f3000
6:panic: because you said to!
7:current pcb at 1e3f70
8:Reading in symbols for ../../i386/i386/machdep.c...done.
9:<prompt>(kgdb)</prompt> <userinput>where</userinput>
10:#0 boot (arghowto=256) (../../i386/i386/machdep.c line 767)
11:#1 0xf0115159 in panic ()
12:#2 0xf01955bd in diediedie () (../../i386/i386/machdep.c line 698)
13:#3 0xf010185e in db_fncall ()
14:#4 0xf0101586 in db_command (-266509132, -266509516, -267381073)
15:#5 0xf0101711 in db_command_loop ()
16:#6 0xf01040a0 in db_trap ()
17:#7 0xf0192976 in kdb_trap (12, 0, -272630436, -266743723)
18:#8 0xf019d2eb in trap_fatal (...)
19:#9 0xf019ce60 in trap_pfault (...)
20:#10 0xf019cb2f in trap (...)
21:#11 0xf01932a1 in exception:calltrap ()
22:#12 0xf0191503 in cnopen (...)
23:#13 0xf0132c34 in spec_open ()
24:#14 0xf012d014 in vn_open ()
25:#15 0xf012a183 in open ()
26:#16 0xf019d4eb in syscall (...)
27:<prompt>(kgdb)</prompt> <userinput>up 10</userinput>
28:Reading in symbols for ../../i386/i386/trap.c...done.
29:#10 0xf019cb2f in trap (frame={tf_es = -260440048, tf_ds = 16, tf_\
30:edi = 3072, tf_esi = -266445372, tf_ebp = -272630356, tf_isp = -27\
31:2630396, tf_ebx = -266427884, tf_edx = 12, tf_ecx = -266427884, tf\
32:_eax = 64772224, tf_trapno = 12, tf_err = -272695296, tf_eip = -26\
33:6672343, tf_cs = -266469368, tf_eflags = 66066, tf_esp = 3072, tf_\
34:ss = -266427884}) (../../i386/i386/trap.c line 283)
35:283 (void) trap_pfault(&amp;frame, FALSE);
36:<prompt>(kgdb)</prompt> <userinput>frame frame-&gt;tf_ebp frame-&gt;tf_eip</userinput>
37:Reading in symbols for ../../i386/isa/pcvt/pcvt_drv.c...done.
38:#0 0xf01ae729 in pcopen (dev=3072, flag=3, mode=8192, p=(struct p\
39:roc *) 0xf07c0c00) (../../i386/isa/pcvt/pcvt_drv.c line 403)
40:403 return ((*linesw[tp-&gt;t_line].l_open)(dev, tp));
41:<prompt>(kgdb)</prompt> <userinput>list</userinput>
42:398
43:399 tp-&gt;t_state |= TS_CARR_ON;
44:400 tp-&gt;t_cflag |= CLOCAL; /* cannot be a modem (:-) */
45:401
46:402 #if PCVT_NETBSD || (PCVT_FREEBSD >= 200)
47:403 return ((*linesw[tp-&gt;t_line].l_open)(dev, tp));
48:404 #else
49:405 return ((*linesw[tp-&gt;t_line].l_open)(dev, tp, flag));
50:406 #endif /* PCVT_NETBSD || (PCVT_FREEBSD >= 200) */
51:407 }
52:<prompt>(kgdb)</prompt> <userinput>print tp</userinput>
53:Reading in symbols for ../../i386/i386/cons.c...done.
54:$1 = (struct tty *) 0x1bae
55:<prompt>(kgdb)</prompt> <userinput>print tp-&gt;t_line</userinput>
56:$2 = 1767990816
57:<prompt>(kgdb)</prompt> <userinput>up</userinput>
58:#1 0xf0191503 in cnopen (dev=0x00000000, flag=3, mode=8192, p=(st\
59:ruct proc *) 0xf07c0c00) (../../i386/i386/cons.c line 126)
60: return ((*cdevsw[major(dev)].d_open)(dev, flag, mode, p));
61:<prompt>(kgdb)</prompt> <userinput>up</userinput>
62:#2 0xf0132c34 in spec_open ()
63:<prompt>(kgdb)</prompt> <userinput>up</userinput>
64:#3 0xf012d014 in vn_open ()
65:<prompt>(kgdb)</prompt> <userinput>up</userinput>
66:#4 0xf012a183 in open ()
67:<prompt>(kgdb)</prompt> <userinput>up</userinput>
68:#5 0xf019d4eb in syscall (frame={tf_es = 39, tf_ds = 39, tf_edi =\
69: 2158592, tf_esi = 0, tf_ebp = -272638436, tf_isp = -272629788, tf\
70:_ebx = 7086, tf_edx = 1, tf_ecx = 0, tf_eax = 5, tf_trapno = 582, \
71:tf_err = 582, tf_eip = 75749, tf_cs = 31, tf_eflags = 582, tf_esp \
72:= -272638456, tf_ss = 39}) (../../i386/i386/trap.c line 673)
73:673 error = (*callp-&gt;sy_call)(p, args, rval);
74:<prompt>(kgdb)</prompt> <userinput>up</userinput>
75:Initial frame selected; you cannot go up.
76:<prompt>(kgdb)</prompt> <userinput>quit</userinput>
77:&prompt.root; <userinput>exit</userinput>
78:exit
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>
</listitem>
</varlistentry>
<varlistentry>
<term>line 20:</term>
<listitem>
<para>This is the location of function <function>trap()</function>
in the stack trace.</para>
</listitem>
</varlistentry>
<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>
</listitem>
</varlistentry>
<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>
<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>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1>
<title>Debugging a crash dump with DDD</title>
<para>Examining a kernel crash dump with a graphical debugger like
<command>ddd</command> is also possible. Add the <option>-k</option>
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>'s graphical interface.</para>
</sect1>
<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>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 config directory
(<filename>/usr/src/sys/<replaceable>arch</replaceable>/conf</filename>)
and edit your configuration file. Uncomment (or add, if it does not
exist) the following line</para>
<programlisting>
makeoptions DEBUG=-g #Build kernel with gdb(1) debug symbols</programlisting>
<para>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>
<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>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-stepping 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>
<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>
<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>
</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>
<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>
<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>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>
</note>
<para>If you want to remove a breakpoint, use</para>
<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>
<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>
<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>
</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>
<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>
<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>
<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.
<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>
<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>
<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>
<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>
<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>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>
</sect1>
<sect1>
<title>On-line Kernel Debugging Using Remote GDB</title>
<para>This feature has been supported since FreeBSD 2.2, and it is
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>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>
<screen>&prompt.user; <userinput>gdb -k kernel</userinput>
GDB is free software and you are welcome to distribute copies of it
under certain conditions; type "show copying" to see the conditions.
There is absolutely no warranty for GDB; type "show warranty" for details.
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>
<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>
<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>
<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>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>
<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>
<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>
</sect1>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->

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

@ -1,164 +0,0 @@
<!--
The FreeBSD Documentation Project
$Id: chapter.sgml,v 1.9 1999-03-08 22:04:43 nik Exp $
-->
<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>
</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>
<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>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
[your code here]
#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>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>
<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
<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>
<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>
</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>
<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
<filename>opt_foo.h</filename>. This can be overridden on the
right-hand side of a rule by specifying another filename.</para>
<para>If there is no
<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>
<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>
<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, <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.
<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>
</sect1>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->

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

@ -1,333 +0,0 @@
<!--
The FreeBSD Documentation Project
$Id: chapter.sgml,v 1.11 1999-08-05 20:48:17 nik Exp $
-->
<chapter id="l10n">
<title>Localization</title>
<sect1 id="russian">
<title>Russian Language (KOI8-R encoding)</title>
<para><emphasis>Contributed by &a.ache; 1 May
1997</emphasis>.</para>
<para>See more info about KOI8-R encoding at <ulink
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>
</step>
<step>
<para>Russian console entry in
<filename>/etc/rc.conf</filename> should looks like:</para>
<programlisting>
keymap=ru.koi8-r
keychange="61 ^[[K"
scrnmap=koi8-r2cp866
font8x16=cp866b-8x16
font8x14=cp866-8x14
font8x8=cp866-8x8</programlisting>
<note>
<para>^[ means that real ESC character must be entered into
<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>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>
<programlisting>
ttyv0 "/usr/libexec/getty Pc" cons25r on secure</programlisting>
</step>
</procedure>
</sect2>
<sect2 id="russian-locale">
<title>Locale Setup</title>
<para><anchor id="russian-env"> There is two environment variables
for locale setup:</para>
<itemizedlist>
<listitem>
<para><envar>LANG</envar> for POSIX &man.setlocale.3; family
functions;</para>
</listitem>
<listitem>
<para><envar>MM_CHARSET</envar> for applications MIME character
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>
<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>
<programlisting>
russian:Russian Users Accounts:\
:charset=KOI8-R:\
: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>
<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>
<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>
</listitem>
<listitem>
<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>
</listitem>
<listitem>
<para>Another variant: call
<screen>&prompt.root; <userinput>adduser -class russian</userinput></screen>
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>
<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>
<itemizedlist>
<listitem>
<para><filename>/etc/profile</filename>:</para>
<programlisting>
LANG=ru_RU.KOI8-R; export LANG
MM_CHARSET=KOI8-R; export MM_CHARSET</programlisting>
</listitem>
<listitem>
<para><filename>/etc/csh.login</filename>:</para>
<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>
<listitem>
<para><filename>/usr/share/skel/dot.profile</filename>:</para>
<para>(similar to <filename>/etc/profile</filename> above);</para>
</listitem>
<listitem>
<para><filename>/usr/share/skel/dot.login</filename>:</para>
<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>
<programlisting>
lp|Russian local line printer:\
:sh:of=/usr/libexec/lpr/ru/koi2alt:\
: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>
<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
<option>-W</option> and <option>-L</option> options.</para>
</sect2>
<sect2 id="russian-xwindow">
<title>X Window Setup</title>
<para>Step by step instructions:</para>
<procedure>
<step>
<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>
</note>
</step>
<step>
<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>
<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>
</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>
<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>
</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>
</sect1>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->

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

@ -1,947 +0,0 @@
<!--
The FreeBSD Documentation Project
$Id: chapter.sgml,v 1.17 1999-08-05 20:48:18 nik Exp $
-->
<chapter id="linuxemu">
<title>Linux Emulation</title>
<para><emphasis>Contributed by &a.handy; and &a.rich;</emphasis></para>
<sect1>
<title>How to Install the Linux Emulator</title>
<para>Linux emulation in FreeBSD has reached a point where it is possible
to run a large fraction of Linux binaries in both a.out and ELF format.
The linux emulation in the 2.1-STABLE branch is capable of running Linux
DOOM and Mathematica; the version present in &rel.current;-RELEASE is
vastly more capable and runs all these as well as Quake, Abuse, IDL,
netrek for Linux and a whole host of other programs.</para>
<para>There are some Linux-specific operating system features that are not
supported on FreeBSD. Linux binaries will not work on FreeBSD if they
use the Linux <filename>/proc</filename> filesystem (which is different
from the optional FreeBSD <filename>/proc</filename> filesystem) or
i386-specific calls, such as enabling virtual 8086 mode.</para>
<para>Depending on which version of FreeBSD you are running, how you get
Linux-emulation up will vary slightly:</para>
<sect2>
<title>Installing Linux Emulation in 2.1-STABLE</title>
<para>The <filename>GENERIC</filename> kernel in 2.1-STABLE is not
configured for linux compatibility so you must reconfigure your kernel
for it. There are two ways to do this: 1. linking the emulator
statically in the kernel itself and 2. configuring your kernel to
dynamically load the linux loadable kernel module (LKM).</para>
<para>To enable the emulator, add the following to your configuration
file (c.f. <filename>/sys/i386/conf/LINT</filename>):</para>
<programlisting>
options COMPAT_LINUX</programlisting>
<para>If you want to run doom or other applications that need shared
memory, also add the following.</para>
<programlisting>
options SYSVSHM</programlisting>
<para>The linux system calls require 4.3BSD system call compatibility.
So make sure you have the following.</para>
<programlisting>
options "COMPAT_43"</programlisting>
<para>If you prefer to statically link the emulator in the kernel rather
than use the loadable kernel module (LKM), then add</para>
<programlisting>
options LINUX</programlisting>
<para>Then run config and install the new kernel as described in the
<link linkend="kernelconfig">kernel configuration</link>
section.</para>
<para>If you decide to use the LKM you must also install the loadable
module. A mismatch of versions between the kernel and loadable module
can cause the kernel to crash, so the safest thing to do is to
reinstall the LKM when you install the kernel.</para>
<screen>&prompt.root; <userinput>cd /usr/src/lkm/linux</userinput>
&prompt.root; <userinput>make all install</userinput></screen>
<para>Once you have installed the kernel and the LKM, you can invoke
`linux' as root to load the LKM.</para>
<screen>&prompt.root; <userinput>linux</userinput>
Linux emulator installed
Module loaded as ID 0</screen>
<para>To see whether the LKM is loaded, run
<command>modstat</command>.</para>
<screen>&prompt.user; modstat
Type Id Off Loadaddr Size Info Rev
Module Name EXEC 0 3 f0baf000 0018 f0bb4000 1 linux_emulator</screen>
<para>You can cause the LKM to be loaded when the system boots in either
of two ways. In FreeBSD 2.2.1-RELEASE and 2.1-STABLE enable it in
<filename>/etc/sysconfig</filename>
<programlisting>
linux=YES</programlisting>
by changing it from NO to YES. FreeBSD 2.1 RELEASE and earlier do not
have such a line and on those you will need to edit
<filename>/etc/rc.local</filename> to add the following line.</para>
<programlisting>
linux</programlisting>
</sect2>
<sect2>
<title>Installing Linux Emulation in 2.2.2-RELEASE and later</title>
<para>It is no longer necessary to specify <literal>options
LINUX</literal> or <literal>options COMPAT_LINUX</literal>. Linux
emulation is done with an LKM (&ldquo;Loadable Kernel Module&rdquo;)
so it can be installed on the fly without having to reboot. You will
need the following things in your startup files, however:</para>
<orderedlist>
<listitem>
<para>In <filename>/etc/rc.conf</filename>, you need the following
line:</para>
<programlisting>
linux_enable=YES</programlisting>
</listitem>
<listitem>
<para>This, in turn, triggers the following action in
<filename>/etc/rc.i386</filename>:</para>
<programlisting>
# Start the Linux binary emulation if requested.
if [ "X${linux_enable}" = X"YES" ]; then echo -n '
linux'; linux &gt; /dev/null 2&gt;&amp;1
fi</programlisting>
</listitem>
</orderedlist>
<para>If you want to verify it is running, modstat will do that:</para>
<screen>&prompt.user; modstat
Type Id Off Loadaddr Size Info Rev Module Name
EXEC 0 4 f09e6000 001c f09ec010 1 linux_mod</screen>
<para>However, there have been reports that this fails on some
2.2-RELEASE and later systems. If for some reason you cannot load the
linux LKM, then statically link the emulator in the kernel by
adding
<programlisting>
options LINUX</programlisting>
to your kernel config file. Then run config and install the new
kernel as described in the <link linkend="kernelconfig">kernel
configuration</link> section.</para>
</sect2>
<sect2>
<title>Installing Linux Runtime Libraries</title>
<sect3>
<title>Installing using the linux_base port</title>
<para>Most linux applications use shared libraries, so you are still
not done until you install the shared libraries. It is possible to
do this by hand, however, it is vastly simpler to just grab the
linux_base port:</para>
<screen>&prompt.root; <userinput>cd /usr/ports/emulators/linux_base</userinput>
&prompt.root; <userinput>make all install</userinput></screen>
<para>and you should have a working linux emulator. Legend (and the
mail archives <!-- smiley -->:-) seems to hold that Linux emulation
works best with linux binaries linked against the ZMAGIC libraries;
QMAGIC libraries (such as those used in Slackware V2.0) may tend to
give the Linuxulator heartburn. Also, expect some programs to
complain about incorrect minor versions of the system libraries. In
general, however, this does not seem to be a problem.</para>
</sect3>
<sect3>
<title>Installing libraries manually</title>
<para>If you do not have the &ldquo;ports&rdquo; distribution, you can
install the libraries by hand instead. You will need the Linux
shared libraries that the program depends on and the runtime linker.
Also, you will need to create a "shadow root" directory,
<filename>/compat/linux</filename>, for Linux libraries on your
FreeBSD system. Any shared libraries opened by Linux programs run
under FreeBSD will look in this tree first. So, if a Linux program
loads, for example, <filename>/lib/libc.so</filename>, FreeBSD will
first try to open <filename>/compat/linux/lib/libc.so</filename>,
and if that does not exist then it will try
<filename>/lib/libc.so</filename>. Shared libraries should be
installed in the shadow tree <filename>/compat/linux/lib</filename>
rather than the paths that the Linux <command>ld.so</command>
reports.</para>
<para>FreeBSD-2.2-RELEASE and later works slightly differently with
respect to <filename>/compat/linux</filename>: all files, not just
libraries, are searched for from the &ldquo;shadow root&rdquo;
<filename>/compat/linux</filename>.</para>
<para>Generally, you will need to look for the shared libraries that
Linux binaries depend on only the first few times that you install
a Linux program on your FreeBSD system. After a while, you will
have a sufficient set of Linux shared libraries on your system to be
able to run newly imported Linux binaries without any extra
work.</para>
</sect3>
<sect3>
<title>How to install additional shared libraries</title>
<para>What if you install the <filename>linux_base</filename> port and
your application still complains about missing shared libraries? How
do you know which shared libraries Linux binaries need, and where to
get them? Basically, there are 2 possibilities (when following these
instructions: you will need to be root on your FreeBSD system to do
the necessary installation steps).</para>
<para>If you have access to a Linux system, see what shared libraries
the application needs, and copy them to your FreeBSD system.
Example: you have just ftp'ed the Linux binary of Doom. Put it on
the Linux system you have access to, and check which shared
libraries it needs by running <command>ldd
linuxxdoom</command>:</para>
<screen>&prompt.user; <userinput>ldd linuxxdoom</userinput>
libXt.so.3 (DLL Jump 3.1) =&gt; /usr/X11/lib/libXt.so.3.1.0
libX11.so.3 (DLL Jump 3.1) =&gt; /usr/X11/lib/libX11.so.3.1.0
libc.so.4 (DLL Jump 4.5pl26) =&gt; /lib/libc.so.4.6.29</screen>
<para>You would need to get all the files from the last column, and
put them under <filename>/compat/linux</filename>, with the names in
the first column as symbolic links pointing to them. This means you
eventually have these files on your FreeBSD system:</para>
<screen>/compat/linux/usr/X11/lib/libXt.so.3.1.0
/compat/linux/usr/X11/lib/libXt.so.3 -&gt; libXt.so.3.1.0
/compat/linux/usr/X11/lib/libX11.so.3.1.0
/compat/linux/usr/X11/lib/libX11.so.3 -&gt; libX11.so.3.1.0
/compat/linux/lib/libc.so.4.6.29 /compat/linux/lib/libc.so.4 -&gt; libc.so.4.6.29</screen>
<note>
<para>Note that if you already have a Linux shared library with a
matching major revision number to the first column of the
<command>ldd</command> output, you will not need to copy the file
named in the last column to your system, the one you already have
should work. It is advisable to copy the shared library anyway if
it is a newer version, though. You can remove the old one, as
long as you make the symbolic link point to the new one. So, if
you have these libraries on your system:</para>
<screen>/compat/linux/lib/libc.so.4.6.27
/compat/linux/lib/libc.so.4 -&gt; libc.so.4.6.27</screen>
<para>and you find a new binary that claims to require a later
version according to the output of <command>ldd</command>:</para>
<screen>libc.so.4 (DLL Jump 4.5pl26) -&gt; libc.so.4.6.29</screen>
<para>If it is only one or two versions out of date in the in the
trailing digit then do not worry about copying
<filename>/lib/libc.so.4.6.29</filename> too, because the program
should work fine with the slightly older version. However, if you
like you can decide to replace the <filename>libc.so</filename>
anyway, and that should leave you with:</para>
<screen>/compat/linux/lib/libc.so.4.6.29
/compat/linux/lib/libc.so.4 -&gt; libc.so.4.6.29</screen>
</note>
<note>
<para>The symbolic link mechanism is <emphasis>only</emphasis>
needed for Linux binaries. The FreeBSD runtime linker takes care
of looking for matching major revision numbers itself and you do
not need to worry about it.</para>
</note>
</sect3>
<sect3>
<title>Configuring the <filename>ld.so</filename> &mdash; for FreeBSD
2.2-RELEASE and later</title>
<para>This section applies only to FreeBSD 2.2-RELEASE and later.
Those running 2.1-STABLE should skip this section.</para>
<para>Finally, if you run FreeBSD 2.2-RELEASE you must make sure that
you have the Linux runtime linker and its config files on your
system. You should copy these files from the Linux system to their
appropriate place on your FreeBSD system (to the
<filename>/compat/linux</filename> tree):</para>
<screen>/compat/linux/lib/ld.so
/compat/linux/etc/ld.so.config</screen>
<para>If you do not have access to a Linux system, you should get the
extra files you need from various ftp sites. Information on where
to look for the various files is appended below. For now, let us
assume you know where to get the files.</para>
<para>Retrieve the following files (all from the same ftp site to
avoid any version mismatches), and install them under
<filename>/compat/linux</filename> (i.e.
<filename>/foo/bar</filename> is installed as
<filename>/compat/linux/foo/bar</filename>):</para>
<screen>/sbin/ldconfig
/usr/bin/ldd
/lib/libc.so.x.y.z
/lib/ld.so</screen>
<para><command>ldconfig</command> and <command>ldd</command> do not
necessarily need to be under <filename>/compat/linux</filename>; you
can install them elsewhere in the system too. Just make sure they
do not conflict with their FreeBSD counterparts. A good idea would
be to install them in <filename>/usr/local/bin</filename> as
<command>ldconfig-linux</command> and
<command>ldd-linux</command>.</para>
<para>Create the file
<filename>/compat/linux/etc/ld.so.conf</filename>, containing the
directories in which the Linux runtime linker should look for shared
libs. It is a plain text file, containing a directory name on each
line. <filename>/lib</filename> and <filename>/usr/lib</filename>
are standard, you could add the following:</para>
<programlisting>
/usr/X11/lib
/usr/local/lib</programlisting>
<para>When a linux binary opens a library such as
<filename>/lib/libc.so</filename> the emulator maps the name to
<filename>/compat/linux/lib/libc.so</filename> internally. All
linux libraries should be installed under /compat/linux (e.g.
<filename>/compat/linux/lib/libc.so</filename>,
<filename>/compat/linux/usr/X11/lib/libX11.so</filename>, etc.) in
order for the emulator to find them.</para>
<para>Those running FreeBSD 2.2-RELEASE should run the Linux ldconfig
program.</para>
<screen>&prompt.root <userinput>cd /compat/linux/lib</userinput>
&prompt.root; <userinput>/compat/linux/sbin/ldconfig</userinput></screen>
<para><command>ldconfig</command> is statically linked, so it does not
need any shared libraries to run. It creates the file
<filename>/compat/linux/etc/ld.so.cache</filename> which contains
the names of all the shared libraries and should be rerun to
recreate this file whenever you install additional shared
libraries.</para>
<para>On 2.1-STABLE do not install
<filename>/compat/linux/etc/ld.so.cache</filename> or run
<command>ldconfig</command>; in 2.1-STABLE the syscalls are
implemented differently and <command>ldconfig</command> is not
needed or used.</para>
<para>You should now be set up for Linux binaries which only need a
shared libc. You can test this by running the Linux
<command>ldd</command> on itself. Supposing that you have it
installed as <command>ldd-linux</command>, it should produce
something like:</para>
<screen>&prompt.root; <userinput>ldd-linux `which ldd-linux`</userinput>
libc.so.4 (DLL Jump 4.5pl26) =&gt; /lib/libc.so.4.6.29</screen>
<para>This being done, you are ready to install new Linux binaries.
Whenever you install a new Linux program, you should check if it
needs shared libraries, and if so, whether you have them installed
in the <filename>/compat/linux</filename> tree. To do this, you run
the Linux version <command>ldd</command> on the new program, and
watch its output. <command>ldd</command> (see also the manual page
for &man.ldd.1;) will print a list of shared libraries
that the program depends on, in the form
<literal><replaceable>majorname</replaceable>
(<replaceable>jumpversion</replaceable>) =&gt;
<replaceable>fullname</replaceable></literal>.</para>
<para>If it prints <literal>not found</literal> instead of
<replaceable>fullname</replaceable> it means that you need an extra
library. The library needed is shown in majorname and will be of
the form
<literal>lib<replaceable>XXXX</replaceable>.so.<replaceable>N</replaceable></literal>.
You will need to find a
<filename>lib<replaceable>XXXX</replaceable>.so.N.mm</filename> on a
Linux ftp site, and install it on your system. The
<replaceable>XXXX</replaceable> (name) and
<replaceable>N</replaceable> (major revision number) should match;
the minor number(s) <replaceable>mm</replaceable> are less
important, though it is advised to take the most recent
version.</para>
</sect3>
</sect2>
<sect2>
<title>Installing Linux ELF binaries</title>
<para>ELF binaries sometimes require an extra step of
&ldquo;branding&rdquo;. If you attempt to run an unbranded ELF
binary, you will get an error message like the following;</para>
<screen>&prompt.user; <userinput>./my-linux-elf-binary</userinput>
ELF binary type not known
Abort</screen>
<para>To help the FreeBSD kernel distinguish between a FreeBSD ELF
binary from a Linux binary, use the &man.brandelf.1; utility.</para>
<screen>&prompt.user; <userinput>brandelf -t Linux my-linux-elf-binary</userinput></screen>
<para>The GNU toolchain now places the appropriate branding information
into ELF binaries automatically, so you should be needing to do this
step increasingly rarely in future.</para>
</sect2>
<sect2>
<title>Configuring the host name resolver</title>
<para>If DNS does not work or you get the messages
<screen>resolv+: "bind" is an invalid keyword resolv+:
"hosts" is an invalid keyword</screen>
then you need to configure a
<filename>/compat/linux/etc/host.conf</filename> file containing:
<programlisting>
order hosts, bind
multi on</programlisting>
where the order here specifies that <filename>/etc/hosts</filename> is
searched first and DNS is searched second. When
<filename>/compat/linux/etc/host.conf</filename> is not installed
linux applications find FreeBSD's <filename>/etc/host.conf</filename>
and complain about the incompatible FreeBSD syntax. You should remove
<literal>bind</literal> if you have not configured a name-server using
the <filename>/etc/resolv.conf</filename> file.</para>
<para>Lastly, those who run 2.1-STABLE need to set an the
<envar>RESOLV_HOST_CONF</envar> environment variable so that
applications will know how to search the host tables. If you run
FreeBSD 2.2-RELEASE or later, you can skip this. For the
<filename>/bin/csh</filename> shell use:</para>
<screen>&prompt.user; <userinput>setenv RESOLV_HOST_CONF /compat/linux/etc/host.conf</userinput></screen>
<para>For <filename>/bin/sh</filename> use:</para>
<screen>&prompt.user; <userinput>RESOLV_HOST_CONF=/compat/linux/etc/host.conf; export RESOLV_HOST_CONF</userinput></screen>
</sect2>
<sect2>
<title>Finding the necessary files</title>
<note>
<para>The information below is valid as of the time this document was
written, but certain details such as names of ftp sites, directories
and distribution names may have changed by the time you read
this.</para>
</note>
<para>Linux is distributed by several groups that make their own set of
binaries that they distribute. Each distribution has its own name,
like &ldquo;Slackware&rdquo; or &ldquo;Yggdrasil&rdquo;. The
distributions are available on a lot of ftp sites. Sometimes the
files are unpacked, and you can get the individual files you need, but
mostly they are stored in distribution sets, usually consisting of
subdirectories with gzipped tar files in them. The primary ftp sites
for the distributions are:</para>
<orderedlist>
<listitem>
<para>sunsite.unc.edu:/pub/Linux/distributions</para>
</listitem>
<listitem>
<para>tsx-11.mit.edu:/pub/linux/distributions</para>
</listitem>
</orderedlist>
<para>Some European mirrors:</para>
<orderedlist>
<listitem>
<para>ftp.luth.se:/pub/linux/distributions</para>
</listitem>
<listitem>
<para>ftp.demon.co.uk:/pub/unix/linux</para>
</listitem>
<listitem>
<para>src.doc.ic.ac.uk:/packages/linux/distributions</para>
</listitem>
</orderedlist>
<para>For simplicity, let us concentrate on Slackware here. This
distribution consists of a number of subdirectories, containing
separate packages. Normally, they are controlled by an install
program, but you can retrieve files &ldquo;by hand&rdquo; too. First
of all, you will need to look in the <filename>contents</filename>
subdir of the distribution. You will find a lot of small text files
here describing the contents of the separate packages. The fastest
way to look something up is to retrieve all the files in the contents
subdirectory, and grep through them for the file you need. Here is an
example of a list of files that you might need, and in which
contents-file you will find it by grepping through them:</para>
<informaltable frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Library</entry>
<entry>Package</entry>
</row>
</thead>
<tbody>
<row>
<entry><filename>ld.so</filename></entry>
<entry>ldso</entry>
</row>
<row>
<entry><filename>ldconfig</filename></entry>
<entry>ldso</entry>
</row>
<row>
<entry><filename>ldd</filename></entry>
<entry>ldso</entry>
</row>
<row>
<entry><filename>libc.so.4</filename></entry>
<entry>shlibs</entry>
</row>
<row>
<entry><filename>libX11.so.6.0</filename></entry>
<entry>xf_lib</entry>
</row>
<row>
<entry><filename>libXt.so.6.0</filename></entry>
<entry>xf_lib</entry>
</row>
<row>
<entry><filename>libX11.so.3</filename></entry>
<entry>oldlibs</entry>
</row>
<row>
<entry><filename>libXt.so.3</filename></entry>
<entry>oldlibs</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>So, in this case, you will need the packages ldso, shlibs, xf_lib
and oldlibs. In each of the contents-files for these packages, look
for a line saying <literal>PACKAGE LOCATION</literal>, it will tell
you on which &ldquo;disk&rdquo; the package is, in our case it will
tell us in which subdirectory we need to look. For our example, we
would find the following locations:</para>
<informaltable frame="none">
<tgroup cols="2">
<thead
<row>
<entry>Package</entry>
<entry>Location</entry>
</row>
</thead>
<tbody>
<row>
<entry>ldso</entry>
<entry>diska2</entry>
</row>
<row>
<entry>shlibs</entry>
<entry>diska2</entry>
</row>
<row>
<entry>oldlibs</entry>
<entry>diskx6</entry>
</row>
<row>
<entry>xf_lib</entry>
<entry>diskx9</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>The locations called
&ldquo;disk<replaceable>XX</replaceable>&rdquo; refer to the
<filename>slakware/<replaceable>XX</replaceable></filename>
subdirectories of the distribution, others may be found in the
<filename>contrib</filename> subdirectory. In this case, we could now
retrieve the packages we need by retrieving the following files
(relative to the root of the Slackware distribution tree):</para>
<itemizedlist>
<listitem>
<para><filename>slakware/a2/ldso.tgz</filename></para>
</listitem>
<listitem>
<para><filename>slakware/a2/shlibs.tgz</filename></para>
</listitem>
<listitem>
<para><filename>slakware/x6/oldlibs.tgz</filename></para>
</listitem>
<listitem>
<para><filename>slakware/x9/xf_lib.tgz</filename></para>
</listitem>
</itemizedlist>
<para>Extract the files from these gzipped tarfiles in your
<filename>/compat/linux</filename> directory (possibly omitting or
afterwards removing files you do not need), and you are done.</para>
<para><emphasis>See also:</emphasis>
<filename>ftp://ftp.FreeBSD.org/pub/FreeBSD/2.0.5-RELEASE/xperimnt/linux-emu/README</filename> and <filename>/usr/src/sys/i386/ibcs2/README.iBCS2</filename></para>
</sect2>
</sect1>
<sect1 id="mathematica">
<title>How to Install Mathematica on FreeBSD</title>
<para><emphasis>Contributed by &a.rich; and &a.chuck;</emphasis></para>
<para>This document shows how to install the Linux binary distribution of
Mathematica 2.2 on FreeBSD 2.1.</para>
<para>Mathematica supports Linux but not FreeBSD as it stands. So once
you have configured your system for Linux compatibility you have most of
what you need to run Mathematica.</para>
<para>For those who already have the student edition of Mathematica for
DOS the cost of upgrading to the Linux version at the time this was
written, March 1996, was &#36;45.00. It can be ordered directly from
Wolfram at (217) 398-6500 and paid for by credit card.</para>
<sect2>
<title>Unpacking the Mathematica distribution</title>
<para>The binaries are currently distributed by Wolfram on CDROM. The
CDROM has about a dozen tar files, each of which is a binary
distribution for one of the supported architectures. The one for
Linux is named <filename>LINUX.TAR</filename>. You can, for example,
unpack this into <filename>/usr/local/Mathematica</filename>:</para>
<screen>&prompt.root; <userinput>cd /usr/local</userinput>
&prompt.root; <userinput>mkdir Mathematica</userinput>
&prompt.root; <userinput>cd Mathematica</userinput>
&prompt.root; <userinput>tar -xvf /cdrom/LINUX.TAR</userinput></screen>
</sect2>
<sect2>
<title>Obtaining your Mathematica Password</title>
<para>Before you can run Mathematica you will have to obtain a password
from Wolfram that corresponds to your &ldquo;machine ID&rdquo;.</para>
<para>Once you have installed the linux compatibility runtime libraries
and unpacked the mathematica you can obtain the &ldquo;machine
ID&rdquo; by running the program <command>mathinfo</command> in the
Install directory.</para>
<screen>&prompt.root; <userinput>cd /usr/local/Mathematica/Install</userinput>
&prompt.root; <userinput>mathinfo</userinput>
LINUX: 'ioctl' fd=5, typ=0x89(), num=0x27 not implemented
richc.isdn.bcm.tmc.edu 9845-03452-90255</screen>
<para>So, for example, the &ldquo;machine ID&rdquo; of
<hostid>richc</hostid> is <literal>9845-03452-90255</literal>. You
can ignore the message about the ioctl that is not implemented. It
will not prevent Mathematica from running in any way and you can
safely ignore it, though you will see the message every time you run
Mathematica.</para>
<para>When you register with Wolfram, either by email, phone or fax, you
will give them the &ldquo;machine ID&rdquo; and they will respond with
a corresponding password consisting of groups of numbers. You need to
add them both along with the machine name and license number in your
mathpass file.</para>
<para>You can do this by invoking:</para>
<screen>&prompt.root; <userinput>cd /usr/local/Mathematica/Install</userinput>
&prompt.root; <userinput>math.install</userinput></screen>
<para>It will ask you to enter your license number and the Wolfram
supplied password. If you get them mixed up or for some reason the
math.install fails, that is OK; you can simply edit the file
<filename>mathpass</filename> in this same directory to correct the
info manually.</para>
<para>After getting past the password, math.install will ask you if you
accept the install defaults provided, or if you want to use your own.
If you are like us and distrust all install programs, you probably
want to specify the actual directories. Beware. Although the
math.install program asks you to specify directories, it will not
create them for you, so you should perhaps have a second window open
with another shell so that you can create them before you give them to
the install program. Or, if it fails, you can create the directories
and then restart the <command>math.install</command> program. The
directories we chose to create beforehand and specify to
<command>math.install</command> were:</para>
<informaltable frame="none">
<tgroup cols="2">
<tbody>
<row>
<entry><filename>/usr/local/Mathematica/bin</filename></entry>
<entry>for binaries</entry>
</row>
<row>
<entry><filename>/usr/local/Mathematica/man/man1</filename></entry>
<entry>for man pages</entry>
</row>
<row>
<entry>/usr/local/Mathematica/lib/X11</entry>
<entry>for the XKeysymb file</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>You can also tell it to use <filename>/tmp/math.record</filename>
for the system record file, where it puts logs of sessions. After
this <command>math.install</command> will continue on to unpacking
things and placing everything where it should go.</para>
<para>The Mathematica Notebook feature is included separately, as the X
Front End, and you have to install it separately. To get the X Front
End stuff correctly installed, cd into the
<filename>/usr/local/Mathematica/FrontEnd</filename> directory and
execute the <command>xfe.install</command> shell script. You will
have to tell it where to put things, but you do not have to create any
directories because it will use the same directories that had been
created for math.install. When it finishes, there should be a new
shell script in <filename>/usr/local/Mathematica/bin</filename> called
<filename>mathematica</filename>.</para>
<para>Lastly, you need to modify each of the shell scripts that
Mathematica has installed. At the beginning of every shell script in
<filename>/usr/local/Mathematica/bin</filename> add the following
line:</para>
<screen>&prompt.user; <userinput>XKEYSYMDB=/usr/local/Mathematica/lib/X11/XKeysymDB; export XKEYSYMDB</userinput></screen>
<para>This tells Mathematica were to find its own
version of the key mapping file <filename>XKeysymDB</filename>.
Without this you will get pages of error messages about missing
key mappings.</para>
<para>On 2.1-STABLE you need to add the following as well:</para>
<screen>&prompt.user; <userinput>RESOLV_HOST_CONF=/compat/linux/etc/host.conf; export RESOLV_HOST_CONF</userinput></screen>
<para>This tells Mathematica to use the linux version of host.conf.
This file has a different syntax from FreeBSD's host.conf, so you will
get an error message about <filename>/etc/host.conf</filename> if you
leave this out.</para>
<para>You might also want to modify your
<filename>/etc/manpath.config</filename> file to read the new man
directory, and you may need to edit your <filename>~/.cshrc</filename>
file to add <filename>/usr/local/Mathematica/bin</filename> to your
path.</para>
<para>That is about all it takes. With this you should be able to type
<command>mathematica</command> and get a really slick looking
Mathematica Notebook screen up. Mathematica has included the Motif
user interfaces, but it is compiled in statically, so you do not need
the Motif libraries. Good luck doing this yourself!</para>
</sect2>
<sect2>
<title>Bugs</title>
<para>The Notebook front end is known to hang sometimes when reading
notebook files with an error messages similar to:</para>
<screen><errorname>File .../Untitled-1.mb appears to be broken for OMPR.257.0</errorname></screen>
<para>We have not found the cause for this, but it only affects the
Notebook's X Window front end, not the mathematica engine itself. So
the command line interface invoked by 'math' is unaffected by this
bug.</para>
</sect2>
<sect2>
<title>Acknowledgments</title>
<para>A well-deserved thanks should go to &a.sos; and &a.peter; who made
linux emulation what it is today, and Michael Smith who drove these
two guys like dogs to get it to the point where it runs Linux binaries
better than linux! <!-- smiley -->:-)</para>
</sect2>
</sect1>
<sect1>
<title>How does the emulation work?</title>
<para>This section is based heavily on an e-mail written to the
<email>chat@FreeBSD.org</email> mailing list, written by Terry Lambert
<email>tlambert@primenet.com</email> (Message ID:
<literal>&lt;199906020108.SAA07001@usr09.primenet.com&gt;</literal>).</para>
<para>FreeBSD has an abstraction called an &ldquo;execution class
loader&rdquo;. This is a wedge into the &man.execve.2; system
call.</para>
<para>What happens is that FreeBSD has a list of loaders, instead of a
single loader with a fallback to the <literal>#!</literal> loader for
running any shell interpreters or shell scripts.</para>
<para>Historically, the only loader on the UNIX platform examined the
magic number (generally the first 4 or 8 bytes of the file) to see if it
was a binary known to the system, and if so, invoked the binary
loader.</para>
<para>If it was not the binary type for the system, the &man.execve.2;
call returned a failure, and the shell attempted to start executing it
as shell commands.</para>
<para>The assumption was a default of &ldquo;whatever the current shell
is&rdquo;.</para>
<para>Later, a hack was made for &man.sh.1; to examine the first two
characters, and if they were <literal>:\n</literal>, then it invoked the
&man.csh.1; shell instead (I believe SCO first made this hack, but am
willing to be corrected).</para>
<para>What FreeBSD does now is go through a list of loaders, with a
generic <literal>#!</literal> loader that knows about interpreters as
the characters which follow to the next whitespace next to last,
followed by a fallback to <filename>/bin/sh</filename>.</para>
<para>For the Linux binary emulation, FreeBSD sees the magic number as an
ELF binary (it makes no distinction between FreeBSD, Solaris, Linux, or
any other OS which has an ELF image type, at this point).</para>
<para>The ELF loader looks for a specialized <emphasis>brand</emphasis>,
which is a comment section in the ELF image, and which is not present on
SVR4/Solaris ELF binaries.</para>
<para>For Linux binaries to function, they must be
<emphasis>branded</emphasis> as type <literal>Linux</literal>; from
&man.brandelf.1;:</para>
<screen>&prompt.root; <userinput>brandelf -t Linux file</userinput></screen>
<para>When this is done, the ELF loader will see the
<literal>Linux</literal> brand on the file.</para>
<para>When the ELF loader sees the <literal>Linux</literal> brand, the
loader replaces a pointer in the <literal>proc</literal>
structure. All system calls are indexed through this pointer (in a
traditional UNIX system, this would be the <literal>sysent[]</literal> structure array, containing the system
calls). In addition, the process is flagged for special handling of the
trap vector for the signal trampoline code, and sever other (minor)
fixups that are handled by the Linux kernel module.</para>
<para>The Linux system call vector contains, among other things, a list of
<literal>sysent[]</literal> entries whose addresses reside in the kernel
module.</para>
<para>When a system call is called by the Linux binary, the trap code
dereferences the system call function pointer off the
<literal>proc</literal> structure, and gets the Linux, not the FreeBSD,
system call entry points.</para>
<para>In addition, the Linux emulation dynamically
<emphasis>reroots</emphasis> lookups; this is, in effect, what the
<literal>union</literal> option to FS mounts ( <emphasis>not</emphasis>
the unionfs!) does. First, an attempt is made to lookup the file in the
<filename>/compat/linux/<replaceable>original-path</replaceable></filename>
directory, <emphasis>then</emphasis> only if that fails, the lookup is
done in the
<filename>/<replaceable>original-path</replaceable></filename>
directory. This makes sure that binaries that require other binaries
can run (e.g., the Linux toolchain can all run under emulation). It
also means that the Linux binaries can load and exec FreeBSD binaries,
if there are no corresponding Linux binaries present, and that you could
place a &man.uname.1; command in the <filename>/compat/linux</filename>
directory tree to ensure that the Linux binaries could not tell they
were not running on Linux.</para>
<para>In effect, there is a Linux kernel in the FreeBSD kernel; the
various underlying functions that implement all of the services provided
by the kernel are identical to both the FreeBSD system call table
entries, and the Linux system call table entries: file system
operations, virtual memory operations, signal delivery, System V IPC,
etc&hellip; The only difference is that FreeBSD binaries get the FreeBSD
<emphasis>glue</emphasis> functions, and Linux binaries get the Linux
<emphasis>glue</emphasis> functions (most older OS's only had their own
<emphasis>glue</emphasis> functions: addresses of functions in a static
global <literal>sysent[]</literal> structure array, instead of addresses
of functions dereferenced off a dynamically initialized pointer in the
<literal>proc</literal> structure of the process making the
call).</para>
<para>Which one is the native FreeBSD ABI? It does not matter. Basically
the only difference is that (currently; this could easily be changed in
a future release, and probably will be after this) the FreeBSD
<emphasis>glue</emphasis> functions are statically linked into the
kernel, and the Linux glue functions can be statically linked, or they
can be accessed via a kernel module.</para>
<para>Yeah, but is this really emulation? No. It is an ABI
implementation, not an emulation. There is no emulator (or simulator,
to cut off the next question) involved.</para>
<para>So why is it called &ldquo;Linux emulation&rdquo;? To make it hard
to sell FreeBSD! <!-- smiley -->8-). Really, it is because the
historical implementation was done at a time when there was really no
word other than that to describe what was going on; saying that FreeBSD
ran Linux binaries was not true, if you did not compile the code in or
load a module, and there needed to be a word to describe what was being
loaded&mdash;hence &ldquo;the Linux emulator&rdquo;.</para>
</sect1>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->

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

@ -1,567 +0,0 @@
<!--
The FreeBSD Documentation Project
$Id: chapter.sgml,v 1.11 1999-08-05 20:48:18 nik Exp $
-->
<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>
<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>
<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>
</sect2>
<sect2>
<title>Mailhost Server Daemon</title>
<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
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><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>
</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
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>
</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>
<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>
</step>
<step>
<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>
</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
<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>
</listitem>
<listitem>
<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>
<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>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 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>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 MX entry for <hostid role="fqdn">freefall.FreeBSD.org</hostid>
at one time.</para>
<programlisting>
freefall MX 30 mail.crl.net
freefall MX 40 agora.rdrop.com
freefall HINFO Pentium FreeBSD
freefall MX 10 freefall.FreeBSD.org
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>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>
</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>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
this as required. If you set the <literal>shell</literal> to
<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
information.</para>
<para>You basically need to add these lines in your DNS server.</para>
<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>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>
<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>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>
</sect2>
<sect2 id="sendmailuucp">
<title>Setting up UUCP.</title>
<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>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
<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>
<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>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
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
<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> hierarchy,
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>
<programlisting>
include(`../m4/cf.m4')
VERSIONID(`<replaceable>Your version number</replaceable>')
OSTYPE(bsd4.4)
FEATURE(nodns)
FEATURE(nocanonify)
FEATURE(mailertable)
define(`UUCP_RELAY', <replaceable>your.uucp.relay</replaceable>)
define(`UUCP_MAX_SIZE', 200000)
MAILER(local)
MAILER(smtp)
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>Once you have this, you need this file called
<filename>/etc/mailertable</filename>. A typical example of this
gender again:</para>
<programlisting>
#
# makemap hash /etc/mailertable.db &lt; /etc/mailertable
#
horus.interface-business.de uucp-dom:horus
.interface-business.de uucp-dom:if-bus
interface-business.de uucp-dom:if-bus
.heep.sax.de smtp8:%1 horus.UUCP
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
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>
<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
<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>
<screen>&prompt.user; <userinput>sendmail -bt</userinput>
ADDRESS TEST MODE (ruleset 3 NOT automatically invoked)
Enter &lt;ruleset&gt; &lt;address&gt;
<prompt>&gt;</prompt> <userinput>0 foo@interface-business.de</userinput>
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>
<sect1 id="mailfaq">
<title>FAQ</title>
<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>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>
<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>
<para>As a good workaround, you can place the line
<programlisting>
search foo.bar.edu bar.edu</programlisting>
instead of the previous
<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>
</sect2>
<sect2>
<title>Sendmail says <errorname>mail loops back to
myself</errorname></title>
<para>This is answered in the sendmail FAQ as follows:</para>
<programlisting>
* I am getting "Local configuration error" messages, such as:
553 relay.domain.net config error: mail loops back to myself
554 &lt;user@domain.net&gt;... Local configuration error
How can I solve this problem?
You have asked mail to the domain (e.g., domain.net) to be
forwarded to a specific host (in this case, relay.domain.net)
by using an MX record, but the relay machine does not recognize
itself as domain.net. Add domain.net to /etc/sendmail.cw
(if you are using FEATURE(use_cw_file)) or add "Cw domain.net"
to /etc/sendmail.cf.</programlisting>
<para>The sendmail FAQ is in
<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>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>
<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>
<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>
<programlisting>
#!/bin/sh
# Put me in /usr/local/bin/pppbigco
( 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>A further refinement of the situation is as follows.</para>
<para>Message stolen from the freebsd-isp mailing list.</para>
<programlisting>
&gt; we provide the secondary mx for a customer. The customer connects to
&gt; our services several times a day automatically to get the mails to
&gt; his primary mx (We do not call his site when a mail for his domains
&gt; arrived). Our sendmail sends the mailqueue every 30 minutes. At the
&gt; moment he has to stay 30 minutes online to be sure that all mail is
&gt; gone to the primary mx.
&gt;
&gt; Is there a command that would initiate sendmail to send all the mails
&gt; now? The user has not root-privileges on our machine of course.
In the 'privacy flags' section of sendmail.cf, there is a definition
Opgoaway,restrictqrun
Remove restrictqrun to allow non-root users to start the queue processing.
You might also like to rearrange the MXs. We are the 1st MX for our
customers like this, and we have defined:
# If we are the best MX for a host, try directly instead of generating
# local config error.
OwTrue
That way a remote site will deliver straight to you, without trying
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>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->

104
en/handbook/mailing-lists.ent
View file

@ -1,104 +0,0 @@
<!--
Names of FreeBSD mailing lists and related software.
$Id: mailing-lists.ent,v 1.3 1999-07-28 20:23:05 nik Exp $
-->
<!ENTITY a.advocacy "FreeBSD advocacy mailing list
<email>freebsd-advocacy@FreeBSD.org</email>">
<!ENTITY a.announce "FreeBSD announcements mailing list
<email>freebsd-announce@FreeBSD.org</email>">
<!ENTITY a.bugs "FreeBSD problem reports mailing list
<email>freebsd-bugs@FreeBSD.org</email>">
<!ENTITY a.chat "FreeBSD chat mailing list
<email>freebsd-chat@FreeBSD.org</email>">
<!ENTITY a.core "FreeBSD core team
<email>freebsd-core@FreeBSD.org</email>">
<!ENTITY a.current "FreeBSD-current mailing list
<email>freebsd-current@FreeBSD.org</email>">
<!ENTITY a.cvsall "FreeBSD CVS commit message mailing list
<email>cvs-all@FreeBSD.org</email>">
<!ENTITY a.database "FreeBSD based Databases mailing list
<email>freebsd-database@FreeBSD.org</email>">
<!ENTITY a.doc "FreeBSD documentation project mailing list
<email>freebsd-doc@FreeBSD.org</email>">
<!ENTITY a.emulation "FreeBSD-emulation mailing list
<email>freebsd-emulation@FreeBSD.org</email>">
<!ENTITY a.fs "FreeBSD filesystem project mailing list
<email>freebsd-fs@FreeBSD.org</email>">
<!ENTITY a.hackers "FreeBSD technical discussions mailing list
<email>freebsd-hackers@FreeBSD.org</email>">
<!ENTITY a.hardware "FreeBSD hardware and equipment mailing list
<email>freebsd-hardware@FreeBSD.org</email>">
<!ENTITY a.isdn "FreeBSD ISDN mailing list
<email>freebsd-isdn@FreeBSD.org</email>">
<!ENTITY a.isp "FreeBSD Internet service provider's mailing list
<email>freebsd-isp@FreeBSD.org</email>">
<!ENTITY a.java "FreeBSD Java Language mailing list
<email>freebsd-java@FreeBSD.org</email>">
<!ENTITY a.jobs "FreeBSD related employment mailing list
<email>freebsd-jobs@FreeBSD.org</email>">
<!ENTITY a.mobile "FreeBSD laptop computer mailing list
<email>freebsd-mobile@FreeBSD.org</email>">
<!ENTITY a.mozilla "FreeBSD port of the Mozilla browser mailing list
<email>freebsd-mozilla@FreeBSD.org</email>">
<!ENTITY a.multimedia "FreeBSD multimedia mailing list
<email>freebsd-multimedia@FreeBSD.org</email>">
<!ENTITY a.net "FreeBSD networking mailing list
<email>freebsd-net@FreeBSD.org</email>">
<!ENTITY a.newbies "FreeBSD new users mailing list
<email>freebsd-newbies@FreeBSD.org</email>">
<!ENTITY a.newbus "New Bus Architecture mailing list
<email>new-bus-arch@bostonradio.org</email>">
<!ENTITY a.ports "FreeBSD ports mailing list
<email>freebsd-ports@FreeBSD.org</email>">
<!ENTITY a.questions "FreeBSD general questions mailing list
<email>freebsd-questions@FreeBSD.org</email>">
<!ENTITY a.scsi "FreeBSD SCSI subsystem mailing list
<email>freebsd-scsi@FreeBSD.org</email>">
<!ENTITY a.security "FreeBSD security mailing list
<email>freebsd-security@FreeBSD.org</email>">
<!ENTITY a.security-notifications "FreeBSD security notifications mailing list
<email>freebsd-security-notifications@FreeBSD.org</email>">
<!ENTITY a.small "FreeBSD-small mailing list
<email>freebsd-small@FreeBSD.org</email>">
<!ENTITY a.smp "FreeBSD symmetric multiprocessing mailing list
<email>freebsd-smp@FreeBSD.org</email>">
<!ENTITY a.stable "FreeBSD-stable mailing list
<email>freebsd-stable@FreeBSD.org</email>">
<!ENTITY a.tokenring "FreeBSD tokenring mailing list
<email>freebsd-tokenring@FreeBSD.org</email>">
<!ENTITY a.majordomo "<email>majordomo@FreeBSD.org</email>">

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

File diff suppressed because it is too large Load diff

10
en/handbook/newsgroups.ent
View file

@ -1,10 +0,0 @@
<!--
Names of FreeBSD newsgroups
$Id: newsgroups.ent,v 1.1 1999-03-04 22:14:06 nik Exp $
-->
<!ENTITY ng.misc "the
<ulink url='news:comp.unix.bsd.freebsd.misc'>comp.unix.bsd.freebsd.misc</ulink>
newsgroup">

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

@ -1,624 +0,0 @@
<!--
The FreeBSD Documentation Project
$Id: chapter.sgml,v 1.13 1999-07-28 20:23:29 nik Exp $
-->
<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>
<sect1>
<title>Officers</title>
<sect2>
<title>FreeBSD Security Officer
<email>security-officer@FreeBSD.org</email></title>
<programlisting>
FreeBSD Security Officer &lt;security-officer@FreeBSD.org&gt;
Fingerprint = 41 08 4E BB DB 41 60 71 F9 E5 0E 98 73 AF 3F 11
-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: 2.6.3i
mQCNAzF7MY4AAAEEAK7qBgPuBejER5HQbQlsOldk3ZVWXlRj54raz3IbuAUrDrQL
h3g57T9QY++f3Mot2LAf5lDJbsMfWrtwPrPwCCFRYQd6XH778a+l4ju5axyjrt/L
Ciw9RrOC+WaPv3lIdLuqYge2QRC1LvKACIPNbIcgbnLeRGLovFUuHi5z0oilAAUR
tDdGcmVlQlNEIFNlY3VyaXR5IE9mZmljZXIgPHNlY3VyaXR5LW9mZmljZXJAZnJl
ZWJzZC5vcmc+iQCVAwUQMX6yrOJgpPLZnQjrAQHyowQA1Nv2AY8vJIrdp2ttV6RU
tZBYnI7gTO3sFC2bhIHsCvfVU3JphfqWQ7AnTXcD2yPjGcchUfc/EcL1tSlqW4y7
PMP4GHZp9vHog1NAsgLC9Y1P/1cOeuhZ0pDpZZ5zxTo6TQcCBjQA6KhiBFP4TJql
3olFfPBh3B/Tu3dqmEbSWpuJAJUDBRAxez3C9RVb+45ULV0BAak8A/9JIG/jRJaz
QbKom6wMw852C/Z0qBLJy7KdN30099zMjQYeC9PnlkZ0USjQ4TSpC8UerYv6IfhV
nNY6gyF2Hx4CbEFlopnfA1c4yxtXKti1kSN6wBy/ki3SmqtfDhPQ4Q31p63cSe5A
3aoHcjvWuqPLpW4ba2uHVKGP3g7SSt6AOYkAlQMFEDF8mz0ff6kIA1j8vQEBmZcD
/REaUPDRx6qr1XRQlMs6pfgNKEwnKmcUzQLCvKBnYYGmD5ydPLxCPSFnPcPthaUb
5zVgMTjfjS2fkEiRrua4duGRgqN4xY7VRAsIQeMSITBOZeBZZf2oa9Ntidr5PumS
9uQ9bvdfWMpsemk2MaRG9BSoy5Wvy8VxROYYUwpT8Cf2iQCVAwUQMXsyqWtaZ42B
sqd5AQHKjAQAvolI30Nyu3IyTfNeCb/DvOe9tlOn/o+VUDNJiE/PuBe1s2Y94a/P
BfcohpKC2kza3NiW6lLTp00OWQsuu0QAPc02vYOyseZWy4y3Phnw60pWzLcFdemT
0GiYS5Xm1o9nAhPFciybn9j1q8UadIlIq0wbqWgdInBT8YI/l4f5sf6JAJUDBRAx
ezKXVS4eLnPSiKUBAc5OBACIXTlKqQC3B53qt7bNMV46m81fuw1PhKaJEI033mCD
ovzyEFFQeOyRXeu25Jg9Bq0Sn37ynISucHSmt2tUD5W0+p1MUGyTqnfqejMUWBzO
v4Xhp6a8RtDdUMBOTtro16iulGiRrCKxzVgEl4i+9Z0ZiE6BWlg5AetoF5n3mGk1
lw==
=ipyA
-----END PGP PUBLIC KEY BLOCK-----</programlisting>
</sect2>
<sect2>
<title>&a.imp;</title>
<programlisting>
Warner Losh &lt;imp@village.org&gt;
aka &lt;imp@FreeBSD.org&gt;
Fingerprint = D4 31 FD B9 F7 90 17 E8 37 C5 E7 7F CF A6 C1 B9
-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: 2.6.2
mQCNAzDzTiAAAAEEAK8D7KWEbVFUrmlqhUEnAvphNIqHEbqqT8s+c5f5c2uHtlcH
V4mV2TlUaDSVBN4+/D70oHmZc4IgiQwMPCWRrSezg9z/MaKlWhaslc8YT6Xc1q+o
EP/fAdKUrq49H0QQbkQk6Ks5wKW6v9AOvdmsS6ZJEcet6d9G4dxynu/2qPVhAAUR
tCBNLiBXYXJuZXIgTG9zaCA8aW1wQHZpbGxhZ2Uub3JnPokAlQMFEDM/SK1VLh4u
c9KIpQEBFPsD/1n0YuuUPvD4CismZ9bx9M84y5sxLolgFEfP9Ux196ZSeaPpkA0g
C9YX/IyIy5VHh3372SDWN5iVSDYPwtCmZziwIV2YxzPtZw0nUu82P/Fn8ynlCSWB
5povLZmgrWijTJdnUWI0ApVBUTQoiW5MyrNN51H3HLWXGoXMgQFZXKWYiQCVAwUQ
MzmhkfUVW/uOVC1dAQG3+AP/T1HL/5EYF0ij0yQmNTzt1cLt0b1e3N3zN/wPFFWs
BfrQ+nsv1zw7cEgxLtktk73wBGM9jUIdJu8phgLtl5a0m9UjBq5oxrJaNJr6UTxN
a+sFkapTLT1g84UFUO/+8qRB12v+hZr2WeXMYjHAFUT18mp3xwjW9DUV+2fW1Wag
YDKJAJUDBRAzOYK1s1pi61mfMj0BARBbA/930CHswOF0HIr+4YYUs1ejDnZ2J3zn
icTZhl9uAfEQq++Xor1x476j67Z9fESxyHltUxCmwxsJ1uOJRwzjyEoMlyFrIN4C
dE0C8g8BF+sRTt7VLURLERvlBvFrVZueXSnXvmMoWFnqpSpt3EmN6TNaLe8Cm87a
k6EvQy0dpnkPKokAlQMFEDD9Lorccp7v9qj1YQEBrRUD/3N4cCMWjzsIFp2Vh9y+
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>
<programlisting>
Satoshi Asami &lt;asami@cs.berkeley.edu&gt;
aka &lt;asami@FreeBSD.org&gt;
Fingerprint = EB 3C 68 9E FB 6C EB 3F DB 2E 0F 10 8F CE 79 CA
-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: 2.6.2
mQCNAzPVyoQAAAEEAL7W+kipxB171Z4SVyyL9skaA7hG3eRsSOWk7lfvfUBLtPog
f3OKwrApoc/jwLf4+Qpdzv5DLEt/6Hd/clskhJ+q1gMNHyZ5ABmUxrTRRNvJMTrb
3fPU3oZj7sL/MyiFaT1zF8EaMP/iS2ZtcFsbYOqGeA8E/58uk4NA0SoeCNiJAAUR
tCVTYXRvc2hpIEFzYW1pIDxhc2FtaUBjcy5iZXJrZWxleS5lZHU+iQCVAwUQM/AT
+EqGN2HYnOMZAQF11QP/eSXb2FuTb1yX5yoo1Im8YnIk1SEgCGbyEbOMMBznVNDy
5g2TAD0ofLxPxy5Vodjg8rf+lfMVtO5amUH6aNcORXRncE83T10JmeM6JEp0T6jw
zOHKz8jRzygYLBayGsNIJ4BGxa4LeaGxJpO1ZEvRlNkPH/YEXK5oQmq9/DlrtYOJ
AEUDBRAz42JT8ng6GBbVvu0BAU8nAYCsJ8PiJpRUGlrz6rxjX8hqM1v3vqFHLcG+
G52nVMBSy+RZBgzsYIPwI5EZtWAKb22JAJUDBRAz4QBWdbtuOHaj97EBAaQPA/46
+NLUp+Wubl90JoonoXocwAg88tvAUVSzsxPXj0lvypAiSI2AJKsmn+5PuQ+/IoQy
lywRsxiQ5GD7C72SZ1yw2WI9DWFeAi+qa4b8n9fcLYrnHpyCY+zxEpu4pam8FJ7H
JocEUZz5HRoKKOLHErzXDiuTkkm72b1glmCqAQvnB4kAlQMFEDPZ3gyDQNEqHgjY
iQEBFfUEALu2C0uo+1Z7C5+xshWRYY5xNCzK20O6bANVJ+CO2fih96KhwsMof3lw
fDso5HJSwgFd8WT/sR+Wwzz6BAE5UtgsQq5GcsdYQuGI1yIlCYUpDp5sgswNm+OA
bX5a+r4F/ZJqrqT1J56Mer0VVsNfe5nIRsjd/rnFAFVfjcQtaQmjiQCVAwUQM9uV
mcdm8Q+/vPRJAQELHgP9GqNiMpLQlZig17fDnCJ73P0e5t/hRLFehZDlmEI2TK7j
Yeqbw078nZgyyuljZ7YsbstRIsWVCxobX5eH1kX+hIxuUqCAkCsWUY4abG89kHJr
XGQn6X1CX7xbZ+b6b9jLK+bJKFcLSfyqR3M2eCyscSiZYkWKQ5l3FYvbUzkeb6K0
IVNhdG9zaGkgQXNhbWkgPGFzYW1pQEZyZWVCU0QuT1JHPg==
=39SC
-----END PGP PUBLIC KEY BLOCK-----</programlisting>
</sect2>
<sect2>
<title>&a.jmb;</title>
<programlisting>
Jonathan M. Bresler &lt;jmb@FreeBSD.org&gt;
f16 Fingerprint16 = 31 57 41 56 06 C1 40 13 C5 1C E3 E5 DC 62 0E FB
-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: PGPfreeware 5.0i for non-commercial use
mQCNAzG2GToAAAEEANI6+4SJAAgBpl53XcfEr1M9wZyBqC0tzpie7Zm4vhv3hO8s
o5BizSbcJheQimQiZAY4OnlrCpPxijMFSaihshs/VMAz1qbisUYAMqwGEO/T4QIB
nWNo0Q/qOniLMxUrxS1RpeW5vbghErHBKUX9GVhxbiVfbwc4wAHbXdKX5jjdAAUR
tCVKb25hdGhhbiBNLiBCcmVzbGVyIDxqbWJARnJlZUJTRC5PUkc+iQCVAwUQNbtI
gAHbXdKX5jjdAQHamQP+OQr10QRknamIPmuHmFYJZ0jU9XPIvTTMuOiUYLcXlTdn
GyTUuzhbEywgtOldW2V5iA8platXThtqC68NsnN/xQfHA5xmFXVbayNKn8H5stDY
2s/4+CZ06mmJfqYmONF1RCbUk/M84rVT3Gn2tydsxFh4Pm32lf4WREZWRiLqmw+J
AJUDBRA0DfF99RVb+45ULV0BAcZ0BACCydiSUG1VR0a5DBcHdtin2iZMPsJUPRqJ
tWvP6VeI8OFpNWQ4LW6ETAvn35HxV2kCcQMyht1kMD+KEJz7r8Vb94TS7KtZnNvk
2D1XUx8Locj6xel5c/Lnzlnnp7Bp1XbJj2u/NzCaZQ0eYBdP/k7RLYBYHQQln5x7
BOuiRJNVU4kAlQMFEDQLcShVLh4uc9KIpQEBJv4D/3mDrD0MM9EYOVuyXik3UGVI
8quYNA9ErVcLdt10NjYc16VI2HOnYVgPRag3Wt7W8wlXShpokfC/vCNt7f5JgRf8
h2a1/MjQxtlD+4/Js8k7GLa53oLon6YQYk32IEKexoLPwIRO4L2BHWa3GzHJJSP2
aTR/Ep90/pLdAOu/oJDUiQCVAwUQMqyL0LNaYutZnzI9AQF25QP9GFXhBrz2tiWz
2+0gWbpcGNnyZbfsVjF6ojGDdmsjJMyWCGw49XR/vPKYIJY9EYo4t49GIajRkISQ
NNiIz22fBAjT2uY9YlvnTJ9NJleMfHr4dybo7oEKYMWWijQzGjqf2m8wf9OaaofE
KwBX6nxcRbKsxm/BVLKczGYl3XtjkcuJAJUDBRA1ol5TZWCprDT5+dUBATzXA/9h
/ZUuhoRKTWViaistGJfWi26FB/Km5nDQBr/Erw3XksQCMwTLyEugg6dahQ1u9Y5E
5tKPxbB69eF+7JXVHE/z3zizR6VL3sdRx74TPacPsdhZRjChEQc0htLLYAPkJrFP
VAzAlSlm7qd+MXf8fJovQs6xPtZJXukQukPNlhqZ94kAPwMFEDSH/kF4tXKgazlt
bxECfk4AoO+VaFVfguUkWX10pPSSfvPyPKqiAJ4xn8RSIe1ttmnqkkDMhLh00mKj
lLQuSm9uYXRoYW4gTS4gQnJlc2xlciA8Sm9uYXRoYW4uQnJlc2xlckBVU2kubmV0
PokAlQMFEDXbdSkB213Sl+Y43QEBV/4D/RLJNTrtAqJ1ATxXWv9g8Cr3/YF0GTmx
5dIrJOpBup7eSSmiM/BL9Is4YMsoVbXCI/8TqA67TMICvq35PZU4wboQB8DqBAr+
gQ8578M7Ekw1OAF6JXY6AF2P8k7hMcVBcVOACELPT/NyPNByG5QRDoNmlsokJaWU
/2ls4QSBZZlb
=zbCw
-----END PGP PUBLIC KEY BLOCK-----</programlisting>
</sect2>
<sect2>
<title>&a.ache;</title>
<programlisting>
Andrey A. Chernov &lt;ache@FreeBSD.org&gt;
aka &lt;ache@nagual.pp.ru&gt;
Key fingerprint = 33 03 9F 48 33 7B 4A 15 63 48 88 0A C4 97 FD 49
-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: 2.6.3ia
mQCNAiqUMGQAAAEEAPGhcD6A2Buey5LYz0sphDLpVgOZc/bb9UHAbaGKUAGXmafs
Dcb2HnsuYGgX/zrQXuCi/wIGtXcZWB97APtKOhFsZnPinDR5n/dde/mw9FnuhwqD
m+rKSL1HlN0z/Msa5y7g16760wHhSR6NoBSEG5wQAHIMMq7Q0uJgpPLZnQjrAAUT
tCVBbmRyZXkgQS4gQ2hlcm5vdiA8YWNoZUBuYWd1YWwucHAucnU+iQCVAwUQM2Ez
u+JgpPLZnQjrAQEyugP8DPnS8ixJ5OeuYgPFQf5sy6l+LrB6hyaS+lgsUPahWjNY
cnaDmfda/q/BV5d4+y5rlQe/pjnYG7/yQuAR3jhlXz8XDrqlBOnW9AtYjDt5rMfJ
aGFTGXAPGZ6k6zQZE0/YurT8ia3qjvuZm3Fw4NJrHRx7ETHRvVJDvxA6Ggsvmr20
JEFuZHJleSBBLiBDaGVybm92IDxhY2hlQEZyZWVCU0Qub3JnPokAlQMFEDR5uVbi
YKTy2Z0I6wEBLgED/2mn+hw4/3peLx0Sb9LNx//NfCCkVefSf2G9Qwhx6dvwbX7h
mFca97h7BQN4GubU1Z5Ffs6TeamSBrotBYGmOCwvJ6S9WigF9YHQIQ3B4LEjskAt
pcjU583y42zM11kkvEuQU2Gde61daIylJyOxsgpjSWpkxq50fgY2kLMfgl/ftCZB
bmRyZXkgQS4gQ2hlcm5vdiA8YWNoZUBuaWV0enNjaGUubmV0PokAlQMFEDR5svDi
YKTy2Z0I6wEBOTQD/0OTCAXIjuak363mjERvzSkVsNtIH9hA1l0w6Z95+iH0fHrW
xXKT0vBZE0y0Em+S3cotLL0bMmVE3F3D3GyxhBVmgzjyx0NYNoiQjYdi+6g/PV30
Cn4vOO6hBBpSyI6vY6qGNqcsawuRtHNvK/53MpOfKwSlICEBYQimcZhkci+EtCJB
bmRyZXkgQS4gQ2hlcm5vdiA8YWNoZUBuYWd1YWwucnU+iQCVAwUQMcm5HeJgpPLZ
nQjrAQHwvQP9GdmAf1gdcuayHEgNkc11macPH11cwWjYjzA2YoecFMGV7iqKK8QY
rr1MjbGXf8DAG8Ubfm0QbI8Lj8iG3NgqIru0c72UuHGSn/APfGGG0AtPX5UK/k7B
gI0Ca2po6NA5nrSp8tDsdEz/4gyea84RXl2prtTf5Jj07hflbRstGXK0MkFuZHJl
eSBBLiBDaGVybm92LCBCbGFjayBNYWdlIDxhY2hlQGFzdHJhbC5tc2suc3U+iQCV
AwUQMCsAo5/rGryoL8h3AQHq1QQAidyNFqA9hvrmMcjpY7csJVFlGvj574Wj4GPa
o3pZeuQaMBmsWqaXLYnWU/Aldb6kTz6+nRcQX50zFH0THSPfApwEW7yybSTI5apJ
mWT3qhKN2vmLNg2yNzhqLTzHLD1lH3i1pfQq8WevrNfjLUco5S/VuekTma/osnzC
Cw7fQzCJAJUDBRAwKvwoa1pnjYGyp3kBARihBACoXr3qfG65hFCyKJISmjOvaoGr
anxUIkeDS0yQdTHzhQ+dwB1OhhK15E0Nwr0MKajLMm90n6+Zdb5y/FIjpPriu8dI
rlHrWZlewa88eEDM+Q/NxT1iYg+HaKDAE171jmLpSpCL0MiJtO0i36L3ekVD7Hv8
vffOZHPSHirIzJOZTYkAlQMFEDAau6zFLUdtDb+QbQEBQX8D/AxwkYeFaYxZYMFO
DHIvSk23hAsjCmUA2Uil1FeWAusb+o8xRfPDc7TnosrIifJqbF5+fcHCG5VSTGlh
Bhd18YWUeabf/h9O2BsQX55yWRuB2x3diJ1xI/VVdG+rxlMCmE4ZR1Tl9x+Mtun9
KqKVpB39VlkCBYQ3hlgNt/TJUY4riQCVAwUQMBHMmyJRltlmbQBRAQFQkwP/YC3a
hs3ZMMoriOlt3ZxGNUUPTF7rIER3j+c7mqGG46dEnDB5sUrkzacpoLX5sj1tGR3b
vz9a4vmk1Av3KFNNvrZZ3/BZFGpq3mCTiAC9zsyNYQ8L0AfGIUO5goCIjqwOTNQI
AOpNsJ5S+nMAkQB4YmmNlI6GTb3D18zfhPZ6uciJAJUCBRAwD0sl4uW74fteFRkB
AWsAA/9NYqBRBKbmltQDpyK4+jBAYjkXBJmARFXKJYTlnTgOHMpZqoVyW96xnaa5
MzxEiu7ZWm5oL10QDIp1krkBP2KcmvfSMMHb5aGCCQc2/P8NlfXAuHtNGzYiI0UA
Iwi8ih/S1liVfvnqF9uV3d3koE7VsQ9OA4Qo0ZL2ggW+/gEaYIkAlQMFEDAOz6qx
/IyHe3rl4QEBIvYD/jIr8Xqo/2I5gncghSeFR01n0vELFIvaF4cHofGzyzBpYsfA
+6pgFI1IM+LUF3kbUkAY/2uSf9U5ECcaMCTWCwVgJVO+oG075SHEM4buhrzutZiM
1dTyTaepaPpTyRMUUx9ZMMYJs7sbqLId1eDwrJxUPhrBNvf/w2W2sYHSY8cdiQCV
AwUQMAzqgHcdkq6JcsfBAQGTxwQAtgeLFi2rhSOdllpDXUwz+SS6bEjFTWgRsWFM
y9QnOcqryw7LyuFmWein4jasjY033JsODfWQPiPVNA3UEnXVg9+n8AvNMPO8JkRv
Cn1eNg0VaJy9J368uArio93agd2Yf/R5r+QEuPjIssVk8hdcy/luEhSiXWf6bLMV
HEA0J+OJAJUDBRAwDUi+4mCk8tmdCOsBAatBBACHB+qtW880seRCDZLjl/bT1b14
5po60U7u6a3PEBkY0NA72tWDQuRPF/Cn/0+VdFNxQUsgkrbwaJWOoi0KQsvlOm3R
rsxKbn9uvEKLxExyKH3pxp76kvz/lEWwEeKvBK+84Pb1lzpG3W7u2XDfi3VQPTi3
5SZMAHc6C0Ct/mjNlYkAlQMFEDAMrPD7wj+NsTMUOQEBJckD/ik4WsZzm2qOx9Fw
erGq7Zwchc+Jq1YeN5PxpzqSf4AG7+7dFIn+oe6X2FcIzgbYY+IfmgJIHEVjDHH5
+uAXyb6l4iKc89eQawO3t88pfHLJWbTzmnvgz2cMrxt94HRvgkHfvcpGEgbyldq6
EB33OunazFcfZFRIcXk1sfyLDvYE
=1ahV
-----END PGP PUBLIC KEY BLOCK-----</programlisting>
</sect2>
<sect2>
<title>&a.jkh;</title>
<programlisting>
Jordan K. Hubbard &lt;jkh@FreeBSD.org&gt;
Fingerprint = 3C F2 27 7E 4A 6C 09 0A 4B C9 47 CD 4F 4D 0B 20
-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: 2.6.3ia
mQCNAzFjX0IAAAEEAML+nm9/kDNPp43ZUZGjYkm2QLtoC1Wxr8JulZXqk7qmhYcQ
jvX+fyoriJ6/7ZlnLe2oG5j9tZOnRLPvMaz0g9CpW6Dz3nkXrNPkmOFV9B8D94Mk
tyFeRJFqnkCuqBj6D+H8FtBwEeeTecSh2tJ0bZZTXnAMhxeOdvUVW/uOVC1dAAUR
tCNKb3JkYW4gSy4gSHViYmFyZCA8amtoQEZyZWVCU0Qub3JnPokBFQMFEDXCTXQM
j46yp4IfPQEBwO8IAIN0J09AXBf86dFUTFGcAMrEQqOF5IL+KGorAjzuYxERhKfD
ZV7jA+sCQqxkWfcVcE20kVyVYqzZIkio9a5zXP6TwA247JkPt54S1PmMDYHNlRIY
laXlNoji+4q3HP2DfHqXRT2859rYpm/fG/v6pWkos5voPKcZ2OFEp9W+Ap88oqw+
5rx4VetZNJq1Epmis4INj6XqNqj85+MOOIYE+f445ohDM6B/Mxazd6cHFGGIR+az
VjZ6lCDMLjzhB5+FqfrDLYuMjqkMTR5z9DL+psUvPlCkYbQ11NEWtEmiIWjUcNJN
GCxGzv5bXk0XPu3ADwbPkFE2usW1cSM7AQFiwuyJAJUDBRAxe+Q9a1pnjYGyp3kB
AV7XA/oCSL/Cc2USpQ2ckwkGpyvIkYBPszIcabSNJAzm2hsU9Qa6WOPxD8olDddB
uJNiW/gznPC4NsQ0N8Zr4IqRX/TTDVf04WhLmd8AN9SOrVv2q0BKgU6fLuk979tJ
utrewH6PR2qBOjAaR0FJNk4pcYAHeT+e7KaKy96YFvWKIyDvc4kAlQMFEDF8ldof
f6kIA1j8vQEBDH4D/0Zm0oNlpXrAE1EOFrmp43HURHbij8n0Gra1w9sbfo4PV+/H
U8ojTdWLy6r0+prH7NODCkgtIQNpqLuqM8PF2pPtUJj9HwTmSqfaT/LMztfPA6PQ
csyT7xxdXl0+4xTDl1avGSJfYsI8XCAy85cTs+PQwuyzugE/iykJO1Bnj/paiQCV
AwUQMXvlBvUVW/uOVC1dAQF2fQP/RfYC6RrpFTZHjo2qsUHSRk0vmsYfwG5NHP5y
oQBMsaQJeSckN4n2JOgR4T75U4vS62aFxgPLJP3lOHkU2Vc7xhAuBvsbGr5RP8c5
LvPOeUEyz6ZArp1KUHrtcM2iK1FBOmY4dOYphWyWMkDgYExabqlrAq7FKZftpq/C
BiMRuaw=
=C/Jw
-----END PGP PUBLIC KEY BLOCK-----</programlisting>
</sect2>
<sect2>
<title>&a.phk;</title>
<programlisting>
Poul-Henning Kamp &lt;phk@FreeBSD.org&gt;
Fingerprint = A3 F3 88 28 2F 9B 99 A2 49 F4 E2 FA 5A 78 8B 3E
-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: 2.6.3ia
mQCNAzAdpMIAAAEEALHDgrFUwhZtb7PbXg3upELoDVEUPFRwnmpJH1rRqyROUGcI
ooVe7u+FQlIs5OsXK8ECs/5Wpe2UrZSzHvjwBYOND5H42YtI5UULZLRCo5bFfTVA
K9Rpo5icfTsYihrzU2nmnycwFMk+jYXyT/ZDYWDP/BM9iLjj0x9/qQgDWPy9AAUR
tCNQb3VsLUhlbm5pbmcgS2FtcCA8cGhrQEZyZWVCU0Qub3JnPokAlQMFEDQQ0aZ1
u244dqP3sQEBu4ID/jXFFeJgs2MdTDNOZM/FbfDhI4qxAbYUsqS3+Ra16yd8Wd/A
jV+IHJE2NomFWl8UrUjCGinXiwzPgK1OfFJrS9Og1wQLvAl0X84BA8MTP9BQr4w7
6I/RbksgUSrVCIO8MJwlydjSPocWGBeXlVjbZxXzyuJk7H+TG+zuI5BuBcNIiQCV
AwUQMwYr2rNaYutZnzI9AQHiIQP/XxtBWFXaBRgVLEhRNpS07YdU+LsZGlLOZehN
9L4UnJFHQQPNOpMey2gF7Y95aBOw5/1xS5vlQpwmRFCntWsm/gqdzK6rulfr1r5A
y94LO5TAC6ucNu396Y4vo1TyD1STnRC466KlvmtQtAtFGgXlORWLL9URLzcRFd1h
D0yXd9aJAJUDBRAxfo19a1pnjYGyp3kBAQqyA/4v64vP3l1F0Sadn6ias761hkz/
SMdTuLzILmofSCC4o4KWMjiWJHs2Soo41QlZi1+xMHzV32JKiwFlGtPHqL+EHyXy
Q4H3vmf9/1KF+0XCaMtgI0wWUMziPSTJK8xXbRRmMDK/0F4TnVVaUhnmf+h5K7O6
XdmejDTa0X/NWcicmIkAlQMFEDF8lef1FVv7jlQtXQEBcnwD/0ro1PpUtlkLmreD
tsGTkNa7MFLegrYRvDDrHOwPZH152W2jPUncY+eArQJakeHiTDmJNpFagLZglhE0
bqJyca+UwCXX+6upAclWHEBMg2byiWMMqyPVEEnpUoHM1sIkgdNWlfQAmipRBfYh
2LyCgWvR8CbtwPYIFvUmGgB3MR87iQCVAwUQMUseXB9/qQgDWPy9AQGPkwP/WEDy
El2Gkvua9COtMAifot2vTwuvWWpNopIEx0Ivey4aVbRLD90gGCJw8OGDEtqFPcNV
8aIiy3fYVKXGZZjvCKd7zRfhNmQn0eLDcymq2OX3aPrMc2rRlkT4Jx425ukR1gsO
qiQAgw91aWhY8dlw/EKzk8ojm52x4VgXaBACMjaJAJUDBRAxOUOg72G56RHVjtUB
AbL4A/9HOn5Qa0lq9tKI/HkSdc5fGQD/66VdCBAb292RbB7CS/EM07MdbcqRRYIa
0+0gwQ3OdsWPdCVgH5RIhp/WiC+UPkR1cY8N9Mg2kTwJfZZfNqN+BgWlgRMPN27C
OhYNl8Q33Nl9CpBLrZWABF44jPeT0EvvTzP/5ZQ7T75EsYKYiYkAlQMFEDDmryQA
8tkJ67sbQQEBPdsEALCj6v1OBuJLLJTlxmmrkqAZPVzt5QdeO3Eqa2tcPWcU0nqP
vHYMzZcZ7oFg58NZsWrhSQQDIB5e+K65Q/h6dC7W/aDskZd64jxtEznX2kt0/MOr
8OdsDis1K2f9KQftrAx81KmVwW4Tqtzl7NWTDXt44fMOtibCwVq8v2DFkTJy
=JKbP
-----END PGP PUBLIC KEY BLOCK-----</programlisting>
</sect2>
<sect2>
<title>&a.rich;</title>
<programlisting>
Rich Murphey &lt;rich@FreeBSD.org&gt;
fingerprint = AF A0 60 C4 84 D6 0C 73 D1 EF C0 E9 9D 21 DB E4
-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: 2.6.2
mQCNAy97V+MAAAEEALiNM3FCwm3qrCe81E20UOSlNclOWfZHNAyOyj1ahHeINvo1
FBF2Gd5Lbj0y8SLMno5yJ6P4F4r+x3jwHZrzAIwMs/lxDXRtB0VeVWnlj6a3Rezs
wbfaTeSVyh5JohEcKdoYiMG5wjATOwK/NAwIPthB1RzRjnEeer3HI3ZYNEOpAAUR
tCRSaWNoIE11cnBoZXkgPHJpY2hAbGFtcHJleS51dG1iLmVkdT6JAJUDBRAve15W
vccjdlg0Q6kBAZTZBACcNd/LiVnMFURPrO4pVRn1sVQeokVX7izeWQ7siE31Iy7g
Sb97WRLEYDi686osaGfsuKNA87Rm+q5F+jxeUV4w4szoqp60gGvCbD0KCB2hWraP
/2s2qdVAxhfcoTin/Qp1ZWvXxFF7imGA/IjYIfB42VkaRYu6BwLEm3YAGfGcSw==
=QoiM
-----END PGP PUBLIC KEY BLOCK-----</programlisting>
</sect2>
<sect2>
<title>&a.jdp;</title>
<programlisting>
John D. Polstra &lt;jdp@polstra.com&gt;
Fingerprint = 54 3A 90 59 6B A4 9D 61 BF 1D 03 09 35 8D F6 0D
-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: 2.6.2
mQCNAzMElMEAAAEEALizp6ZW9QifQgWoFmG3cXhzQ1+Gt+a4S1adC/TdHdBvw1M/
I6Ok7TC0dKF8blW3VRgeHo4F3XhGn+n9MqIdboh4HJC5Iiy63m98sVLJSwyGO4oM
dkEGyyCLxqP6h/DU/tzNBdqFzetGtYvU4ftt3RO0a506cr2CHcdm8Q+/vPRJAAUR
tCFKb2huIEQuIFBvbHN0cmEgPGpkcEBwb2xzdHJhLmNvbT6JAJUDBRAzBNBE9RVb
+45ULV0BAWgiA/0WWO3+c3qlptPCHJ3DFm6gG/qNKsY94agL/mHOr0fxMP5l2qKX
O6a1bWkvGoYq0EwoKGFfn0QeHiCl6jVi3CdBX+W7bObMcoi+foqZ6zluOWBC1Jdk
WQ5/DeqQGYXqbYjqO8voCScTAPge3XlMwVpMZTv24u+nYxtLkE0ZcwtY9IkAlQMF
EDMEt/DHZvEPv7z0SQEBXh8D/2egM5ckIRpGz9kcFTDClgdWWtlgwC1iI2p9gEhq
aufy+FUJlZS4GSQLWB0BlrTmDC9HuyQ+KZqKFRbVZLyzkH7WFs4zDmwQryLV5wkN
C4BRRBXZfWy8s4+zT2WQD1aPO+ZsgRauYLkJgTvXTPU2JCN62Nsd8R7bJS5tuHEm
7HGmiQCVAwUQMwSvHB9/qQgDWPy9AQFAhAQAgJ1AlbKITrEoJ0+pLIsov3eQ348m
SVHEBGIkU3Xznjr8NzT9aYtq4TIzt8jplqP3QoV1ka1yYpZf0NjvfZ+ffYp/sIaU
wPbEpgtmHnVWJAebMbNs/Ad1w8GDvxEt9IaCbMJGZnHmfnEqOBIxF7VBDPHHoJxM
V31K/PIoYsHAy5w=
=cHFa
-----END PGP PUBLIC KEY BLOCK-----</programlisting>
</sect2>
<sect2>
<title>&a.guido;</title>
<programlisting>
Guido van Rooij &lt;guido@gvr.win.tue.nl&gt;
Fingerprint = 16 79 09 F3 C0 E4 28 A7 32 62 FA F6 60 31 C0 ED
-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: 2.6.2
mQCNAzGeO84AAAEEAKKAY91Na//DXwlUusr9GVESSlVwVP6DyH1wcZXhfN1fyZHq
SwhMCEdHYoojQds+VqD1iiZQvv1RLByBgj622PDAPN4+Z49HjGs7YbZsUNuQqPPU
wRPpP6ty69x1hPKq1sQIB5MS4radpCM+4wbZbhxv7l4rP3RWUbNaYutZnzI9AAUR
tCZHdWlkbyB2YW4gUm9vaWogPGd1aWRvQGd2ci53aW4udHVlLm5sPokAlQMFEDMG
Hcgff6kIA1j8vQEBbYgD/jm9xHuUuY+iXDkOzpCXBYACYEZDV913MjtyBAmaVqYo
Rh5HFimkGXe+rCo78Aau0hc57fFMTsJqnuWEqVt3GRq28hSK1FOZ7ni9/XibHcmN
rt2yugl3hYpClijo4nrDL1NxibbamkGW/vFGcljS0jqXz6NDVbGx5Oo7HBByxByz
iQCVAwUQMhmtVjt/x7zOdmsfAQFuVQQApsVUTigT5YWjQA9Nd5Z0+a/oVtZpyw5Z
OljLJP3vqJdMa6TidhfcatjHbFTve5x1dmjFgMX/MQTd8zf/+Xccy/PX4+lnKNpP
eSf1Y4aK+E8KHmBGd6GzX6CIboyGYLS9e3kGnN06F2AQtaLyJFgQ71wRaGuyKmQG
FwTn7jiKb1aJAJUDBRAyEOLXPt3iN6QQUSEBATwQA/9jqu0Nbk154+Pn+9mJX/YT
fYR2UqK/5FKCqgL5Nt/Deg2re0zMD1f8F9Dj6vuAAxq8hnOkIHKlWolMjkRKkzJi
mSPEWl3AuHJ31k948J8it4f8kq/o44usIA2KKVMlI63Q/rmNdfWCyiYQEVGcRbTm
GTdZIHYCOgV5dOo4ebFqgYkAlQMFEDIE1nMEJn15jgpJ0QEBW6kEAKqN8XSgzTqf
CrxFXT07MlHhfdbKUTNUoboxCGCLNW05vf1A8F5fdE5i14LiwkldWIzPxWD+Sa3L
fNPCfCZTaCiyGcLyTzVfBHA18MBAOOX6JiTpdcm22jLGUWBf/aJK3yz/nfbWntd/
LRHysIdVp29lP5BF+J9/Lzbb/9LxP1taiQCVAwUQMgRXZ44CzbsJWQz9AQFf7gP/
Qa2FS5S6RYKG3rYanWADVe/ikFV2lxuM1azlWbsmljXvKVWGe6cV693nS5lGGAjx
lbd2ADwXjlkNhv45HLWFm9PEveO9Jjr6tMuXVt8N2pxiX+1PLUN9CtphTIU7Yfjn
s6ryZZfwGHSfIxNGi5ua2SoXhg0svaYnxHxXmOtH24iJAJUDBRAyAkpV8qaAEa3W
TBkBARfQBAC+S3kbulEAN3SI7/A+A/dtl9DfZezT9C4SRBGsl2clQFMGIXmMQ/7v
7lLXrKQ7U2zVbgNfU8smw5h2vBIL6f1PyexSmc3mz9JY4er8KeZpcf6H0rSkHl+i
d7TF0GvuTdNPFO8hc9En+GG6QHOqbkB4NRZ6cwtfwUMhk2FHXBnjF4kAlQMFEDH5
FFukUJAsCdPmTQEBe74EAMBsxDnbD9cuI5MfF/QeTNEG4BIVUZtAkDme4Eg7zvsP
d3DeJKCGeNjiCWYrRTCGwaCWzMQk+/+MOmdkI6Oml+AIurJLoHceHS9jP1izdP7f
N2jkdeJSBsixunbQWtUElSgOQQ4iF5kqwBhxtOfEP/L9QsoydRMR1yB6WPD75H7V
iQCVAwUQMZ9YNGtaZ42Bsqd5AQH0PAQAhpVlAc3ZM/KOTywBSh8zWKVlSk3q/zGn
k7hJmFThnlhH1723+WmXE8aAPJi+VXOWJUFQgwELJ6R8jSU2qvk2m1VWyYSqRKvc
VRQMqT2wjss0GE1Ngg7tMrkRHT0il7E2xxIb8vMrIwmdkbTfYqBUhhGnsWPHZHq7
MoA1/b+rK7CJAJUDBRAxnvXh3IDyptUyfLkBAYTDA/4mEKlIP/EUX2Zmxgrd/JQB
hqcQlkTrBAaDOnOqe/4oewMKR7yaMpztYhJs97i03Vu3fgoLhDspE55ooEeHj0r4
cOdiWfYDsjSFUYSPNVhW4OSruMA3c29ynMqNHD7hpr3rcCPUi7J2RncocOcCjjK2
BQb/9IAUNeK4C9gPxMEZLokAlQMFEDGeO86zWmLrWZ8yPQEBEEID/2fPEUrSX3Yk
j5TJPFZ9MNX0lEo7AHYjnJgEbNI4pYm6C3PnMlsYfCSQDHuXmRQHAOWSdwOLvCkN
F8eDaF3M6u0urgeVJ+KVUnTz2+LZoZs12XSZKCte0HxjbvPpWMTTrYyimGezH79C
mgDVjsHaYOx3EXF0nnDmtXurGioEmW1J
=mSvM
-----END PGP PUBLIC KEY BLOCK-----</programlisting>
</sect2>
<sect2>
<title>&a.peter;</title>
<programlisting>
Peter Wemm &lt;peter@FreeBSD.org&gt;
aka &lt;peter@spinner.dialix.com&gt;
aka &lt;peter@haywire.dialix.com&gt;
aka &lt;peter@perth.dialix.oz.au&gt;
Key fingerprint = 47 05 04 CA 4C EE F8 93 F6 DB 02 92 6D F5 58 8A
-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: 2.6.3ia
mQCNAy9/FJwAAAEEALxs9dE9tFd0Ru1TXdq301KfEoe5uYKKuldHRBOacG2Wny6/
W3Ill57hOi2+xmq5X/mHkapywxvy4cyLdt31i4GEKDvxpDvEzAYcy2n9dIup/eg2
kEhRBX9G5k/LKM4NQsRIieaIEGGgCZRm0lINqw495aZYrPpO4EqGN2HYnOMZAAUT
tCVQZXRlciBXZW1tIDxwZXRlckBoYXl3aXJlLmRpYWxpeC5jb20+iQCVAwUQMwWT
cXW7bjh2o/exAQEFkQP+LIx5zKlYp1uR24xGApMFNrNtjh+iDIWnxxb2M2Kb6x4G
9z6OmbUCoDTGrX9SSL2Usm2RD0BZfyv9D9QRWC2TSOPkPRqQgIycc11vgbLolJJN
eixqsxlFeKLGEx9eRQCCbo3dQIUjc2yaOe484QamhsK1nL5xpoNWI1P9zIOpDiGJ
AJUDBRAxsRPqSoY3Ydic4xkBAbWLA/9q1Fdnnk4unpGQsG31Qbtr4AzaQD5m/JHI
4gRmSmbj6luJMgNG3fpO06Gd/Z7uxyCJB8pTst2a8C/ljOYZxWT+5uSzkQXeMi5c
YcI1sZbUpkHtmqPW623hr1PB3ZLA1TIcTbQW+NzJsxQ1Pc6XG9fGkT9WXQW3Xhet
AP+juVTAhLQlUGV0ZXIgV2VtbSA8cGV0ZXJAcGVydGguZGlhbGl4Lm96LmF1PokA
lQMFEDGxFCFKhjdh2JzjGQEB6XkD/2HOwfuFrnQUtdwFPUkgtEqNeSr64jQ3Maz8
xgEtbaw/ym1PbhbCk311UWQq4+izZE2xktHTFClJfaMnxVIfboPyuiSF99KHiWnf
/Gspet0S7m/+RXIwZi1qSqvAanxMiA7kKgFSCmchzas8TQcyyXHtn/gl9v0khJkb
/fv3R20btB5QZXRlciBXZW1tIDxwZXRlckBGcmVlQlNELm9yZz6JAJUDBRAxsRJd
SoY3Ydic4xkBAZJUA/4i/NWHz5LIH/R4IF/3V3LleFyMFr5EPFY0/4mcv2v+ju9g
brOEM/xd4LlPrx1XqPeZ74JQ6K9mHR64RhKR7ZJJ9A+12yr5dVqihe911KyLKab9
4qZUHYi36WQu2VtLGnw/t8Jg44fQSzbBF5q9iTzcfNOYhRkSD3BdDrC3llywO7Ql
UGV0ZXIgV2VtbSA8cGV0ZXJAc3Bpbm5lci5kaWFsaXguY29tPokAlQMFEDGxEi1K
hjdh2JzjGQEBdA4EAKmNFlj8RF9HQsoI3UabnvYqAWN5wCwEB4u+Zf8zq6OHic23
TzoK1SPlmSdBE1dXXQGS6aiDkLT+xOdeewNs7nfUIcH/DBjSuklAOJzKliXPQW7E
kuKNwy4eq5bl+j3HB27i+WBXhn6OaNNQY674LGaR41EGq44Wo5ATcIicig/z
=gv+h
-----END PGP PUBLIC KEY BLOCK-----</programlisting>
</sect2>
<sect2>
<title>&a.joerg;</title>
<programlisting>
Type Bits/KeyID Date User ID
pub 1024/76A3F7B1 1996/04/27 Joerg Wunsch &lt;joerg_wunsch@uriah.heep.sax.de&gt;
Key fingerprint = DC 47 E6 E4 FF A6 E9 8F 93 21 E0 7D F9 12 D6 4E
Joerg Wunsch &lt;joerg_wunsch@interface-business.de&gt;
Joerg Wunsch &lt;j@uriah.heep.sax.de&gt;
Joerg Wunsch &lt;j@interface-business.de&gt;
-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: 2.6.3ia
mQCNAzGCFeAAAAEEAKmRBU2Nvc7nZy1Ouid61HunA/5hF4O91cXm71/KPaT7dskz
q5sFXvPJPpawwvqHPHfEbAK42ZaywyFp59L1GaYj87Pda+PlAYRJyY2DJl5/7JPe
ziq+7B8MdvbX6D526sdmcR+jPXPbHznASjkx9DPmK+7TgFujyXW7bjh2o/exAAUR
tC1Kb2VyZyBXdW5zY2ggPGpvZXJnX3d1bnNjaEB1cmlhaC5oZWVwLnNheC5kZT6J
AJUDBRA0FFkBs1pi61mfMj0BAfDCA/oCfkjrhvRwRCpSL8klJ1YDoUJdmw+v4nJc
pw3OpYXbwKOPLClsE7K3KCQscHel7auf91nrekAwbrXv9Clp0TegYeAQNjw5vZ9f
L6UZ5l3fH8E2GGA7+kqgNWs1KxAnG5GdUvJ9viyrWm8dqWRGo+loDWlZ12L2OgAD
fp7jVZTI1okAlQMFEDQPrLoff6kIA1j8vQEB2XQEAK/+SsQPCT/X4RB/PBbxUr28
GpGJMn3AafAaA3plYw3nb4ONbqEw9tJtofAn4UeGraiWw8nHYR2DAzoAjR6OzuX3
TtUV+57BIzrTPHcNkb6h8fPuHU+dFzR+LNoPaGJsFeov6w+Ug6qS9wa5FGDAgaRo
LHSyBxcRVoCbOEaS5S5EiQCVAwUQM5BktWVgqaw0+fnVAQGKPwP+OiWho3Zm2GKp
lEjiZ5zx3y8upzb+r1Qutb08jr2Ewja04hLg0fCrt6Ad3DoVqxe4POghIpmHM4O4
tcW92THQil70CLzfCxtfUc6eDzoP3krD1/Gwpm2hGrmYA9b/ez9+r2vKBbnUhPmC
glx5pf1IzHU9R2XyQz9Xu7FI2baOSZqJAJUDBRAyCIWZdbtuOHaj97EBAVMzA/41
VIph36l+yO9WGKkEB+NYbYOz2W/kyi74kXLvLdTXcRYFaCSZORSsQKPGNMrPZUoL
oAKxE25AoCgl5towqr/sCcu0A0MMvJddUvlQ2T+ylSpGmWchqoXCN7FdGyxrZ5zz
xzLIvtcio6kaHd76XxyJpltCASupdD53nEtxnu8sRrQxSm9lcmcgV3Vuc2NoIDxq
b2VyZ193dW5zY2hAaW50ZXJmYWNlLWJ1c2luZXNzLmRlPokAlQMFEDIIhfR1u244
dqP3sQEBWoID/RhBm+qtW+hu2fqAj9d8CVgEKJugrxZIpXuCKFvO+bCgQtogt9EX
+TJh4s8UUdcFkyEIu8CT2C3Rrr1grvckfxvrTgzSzvtYyv1072X3GkVY+SlUMBMA
rdl1qNW23oT7Q558ajnsaL065XJ5m7HacgTTikiofYG8i1s7TrsEeq6PtCJKb2Vy
ZyBXdW5zY2ggPGpAdXJpYWguaGVlcC5zYXguZGU+iQCVAwUQMaS91D4gHQUlG9CZ
AQGYOwQAhPpiobK3d/fz+jWrbQgjkoO+j39glYGXb22+6iuEprFRs/ufKYtjljNT
NK3B4DWSkyIPawcuO4Lotijp6jke2bsjFSSashGWcsJlpnwsv7EeFItT3oWTTTQQ
ItPbtNyLW6M6xB+jLGtaAvJqfOlzgO9BLfHuA2LY+WvbVW447SWJAJUDBRAxqWRs
dbtuOHaj97EBAXDBA/49rzZB5akkTSbt/gNd38OJgC+H8N5da25vV9dD3KoAvXfW
fw7OxIsxvQ/Ab+rJmukrrWxPdsC+1WU1+1rGa4PvJp/VJRDes2awGrn+iO7/cQoS
IVziC27JpcbvjLvLVcBIiy1yT/RvJ+87a3jPRHt3VFGcpFh4KykxxSNiyGygl4kA
lQMFEDGCUB31FVv7jlQtXQEB5KgD/iIJZe5lFkPr2B/Cr7BKMVBot1/JSu05NsHg
JZ3uK15w4mVtNPZcFi/dKbn+qRM6LKDFe/GF0HZD/ZD1FJt8yQjzF2w340B+F2GG
EOwnClqZDtEAqnIBzM/ECQQqH+6Bi8gpkFZrFgg5eON7ikqmusDnOlYStM/CBfgp
SbR8kDmFtCZKb2VyZyBXdW5zY2ggPGpAaW50ZXJmYWNlLWJ1c2luZXNzLmRlPokA
lQMFEDHioSdlYKmsNPn51QEByz8D/10uMrwP7MdaXnptd1XNFhpaAPYTVAOcaKlY
OGI/LLR9PiU3FbqXO+7INhaxFjBxa0Tw/p4au5Lq1+Mx81edHniJZNS8tz3I3goi
jIC3+jn2gnVAWnK5UZUTUVUn/JLVk/oSaIJNIMMDaw4J9xPVVkb+Fh1A+XqtPsVa
YESrNp0+iQCVAwUQMwXkzcdm8Q+/vPRJAQEA4QQAgNNX1HFgXrMetDb+w6yEGQDk
JCDAY9b6mA2HNeKLQAhsoZl4HwA1+iuQaCgo3lyFC+1Sf097OUTs74z5X1vCedqV
oFw9CxI3xuctt3pJCbbN68flOlnq0WdYouWWGlFwLlh5PEy//VtwX9lqgsizlhzi
t+fX6BT4BgKi5baDhrWJAJUDBRAyCKveD9eCJxX4hUkBAebMA/9mRPy6K6i7TX2R
jUKSl2p5oYrXPk12Zsw4ijuktslxzQhOCyMSCGK2UEC4UM9MXp1H1JZQxN/DcfnM
7VaUt+Ve0wZ6DC9gBSHJ1hKVxHe5XTj26mIr4rcXNy2XEDMK9QsnBxIAZnBVTjSO
LdhqqSMp3ULLOpBlRL2RYrqi27IXr4kAlQMFEDGpbnd1u244dqP3sQEBJnQD/RVS
Azgf4uorv3fpbosI0LE3LUufAYGBSJNJnskeKyudZkNkI5zGGDwVneH/cSkKT4OR
ooeqcTBxKeMaMuXPVl30QahgNwWjfuTvl5OZ8orsQGGWIn5FhqYXsKkjEGxIOBOf
vvlVQ0UbcR0N2+5F6Mb5GqrXZpIesn7jFJpkQKPU
=97h7
-----END PGP PUBLIC KEY BLOCK-----</programlisting>
</sect2>
</sect1>
<sect1>
<title>Developers</title>
<sect2>
<title>&a.wosch;</title>
<programlisting>
Type Bits/KeyID Date User ID
pub 1024/2B7181AD 1997/08/09 Wolfram Schneider &lt;wosch@FreeBSD.org&gt;
Key fingerprint = CA 16 91 D9 75 33 F1 07 1B F0 B4 9F 3E 95 B6 09
-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: 2.6.3ia
mQCNAzPs+aEAAAEEAJqqMm2I9CxWMuHDvuVO/uh0QT0az5ByOktwYLxGXQmqPG1G
Q3hVuHWYs5Vfm/ARU9CRcVHFyqGQ3LepoRhDHk+JcASHan7ptdFsz7xk1iNNEoe0
vE2rns38HIbiyQ/2OZd4XsyhFOFtExNoBuyDyNoe3HbHVBQT7TmN/mkrcYGtAAUR
tCVXb2xmcmFtIFNjaG5laWRlciA8d29zY2hARnJlZUJTRC5vcmc+iQCVAwUQNxnH
AzmN/mkrcYGtAQF5vgP/SLOiI4AwuPHGwUFkwWPRtRzYSySXqwaPCop5mVak27wk
pCxGdzoJO2UgcE812Jt92Qas91yTT0gsSvOVNATaf0TM3KnKg5ZXT1QIzYevWtuv
2ovAG4au3lwiFPDJstnNAPcgLF3OPni5RCUqBjpZFhb/8YDfWYsMcyn4IEaJKre0
JFdvbGZyYW0gU2NobmVpZGVyIDxzY2huZWlkZXJAemliLmRlPokAlQMFEDcZxu85
jf5pK3GBrQEBCRgD/jPj1Ogx4O769soiguL1XEHcxhqtrpKZkKwxmDLRa0kJFwLp
bBJ3Qz3vwaB7n5gQU0JiL1B2M7IxVeHbiIV5pKp7FD248sm+HZvBg6aSnCg2JPUh
sHd1tK5X4SB5cjFt3Cj0LIN9/c9EUxm3SoML9bovmze60DckErrRNOuTk1IntCJX
b2xmcmFtIFNjaG5laWRlciA8d29zY2hAYXBmZWwuZGU+iQEVAwUQNmfWXAjJLLJO
sC7dAQEASAgAnE4g2fwMmFkQy17ATivljEaDZN/m0GdXHctdZ8CaPrWk/9/PTNK+
U6xCewqIKVwtqxVBMU1VpXUhWXfANWCB7a07D+2GrlB9JwO5NMFJ6g0WI/GCUXjC
xb3NTkNsvppL8Rdgc8wc4f23GG4CXVggdTD2oUjUH5Bl7afgOT4xLPAqePhS7hFB
UnMsbA94OfxPtHe5oqyaXt6cXH/SgphRhzPPZq0yjg0Ef+zfHVamvZ6Xl2aLZmSv
Cc/rb0ShYDYi39ly9OPPiBPGbSVw2Gg804qx3XAKiTFkLsbYQnRt7WuCPsOVjFkf
CbQS31TaclOyzenZdCAezubGIcrJAKZjMIkAlQMFEDPs+aE5jf5pK3GBrQEBlIAD
/3CRq6P0m1fi9fbPxnptuipnoFB/m3yF6IdhM8kSe4XlXcm7tS60gxQKZgBO3bDA
5QANcHdl41Vg95yBAZepPie6iQeAAoylRrONeIy6XShjx3S0WKmA4+C8kBTL+vwa
UqF9YJ1qesZQtsXlkWp/Z7N12RkueVAVQ7wRPwfnz6E3tC5Xb2xmcmFtIFNjaG5l
aWRlciA8d29zY2hAcGFua2UuZGUuZnJlZWJzZC5vcmc+iQCVAwUQNxnEqTmN/mkr
cYGtAQFnpQP9EpRZdG6oYN7d5abvIMN82Z9x71a4QBER+R62mU47wqdRG2b6jMMh
3k07b2oiprVuPhRw/GEPPQevb6RRT6SD9CPYAGfK3MDE8ZkMj4d+7cZDRJQ35sxv
gAzQwuA9l7kS0mt5jFRPcEg5/KpuyehRLckjx8jpEM7cEJDHXhBIuVg=
=3V1R
-----END PGP PUBLIC KEY BLOCK-----</programlisting>
</sect2>
<sect2>
<title>&a.brian;</title>
<programlisting>
Type Bits/KeyID Date User ID
pub 1024/666A7421 1997/04/30 Brian Somers &lt;brian@awfulhak.org&gt;
Key fingerprint = 2D 91 BD C2 94 2C 46 8F 8F 09 C4 FC AD 12 3B 21
Brian Somers &lt;brian@uk.FreeBSD.org&gt;
Brian Somers &lt;brian@OpenBSD.org&gt;
Brian Somers &lt;brian@FreeBSD.org&gt;
-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: 2.6.3ia
mQCNAzNmogUAAAEEALdsjVsV2dzO8UU4EEo7z3nYuvB2Q6YJ8sBUYjB8/vfR5oZ9
7aEQjgY5//pXvS30rHUB9ghk4kIFSljzeMudE0K2zH5n2sxpLbBKWZRDLS7xnrDC
I3j9CNKwQBzMPs0fUT46gp96nf1X8wPiJXkDUEia/c0bRbXlLw7tvOdmanQhAAUR
tCFCcmlhbiBTb21lcnMgPGJyaWFuQGF3ZnVsaGFrLm9yZz6JAJUDBRA3Fjs4H3+p
CANY/L0BAZOxBACTZ1zPdaJzEdT4AfrebQbaU4ytEeodnVXZIkc8Il+LDlDOUAIe
k5PgnHTRM4yiwcZuYQrCDRFgdOofcFfRo0PD7mGFzd22qPGmbvHiDBCYCyhlkPXW
IDeoA1cX77JlU1NFdy0dZwuX7csaMlpjCkOPc7+856mr6pQi48zj7yZtrYkAlQMF
EDcUqZ2dZ0EADG4SFQEBEm0EAL2bBNc4vpxPrg3ATdZ/PekpL6lYj3s9pBf8f7eY
LXq438A/ywiWkrL74gXxcZ2Ey9AHZW+rbJPzUbrfMAgP3uWobeSvDyKRo1wtKnTY
Hy+OEIbBIHDmIUuK3L7KupBf7WAI46Q7fnyz0txvtRruDjvfoyl9/TSRfIKcaw2a
INh7iQCVAwUQNwyWpmdKPfFUsXG5AQEIrAQAmukv2u9ihcnO2Zaak265I+gYozu+
biAngdXNfhTGMeExFzdzQ8Qe7EJugMpIDEkJq2goY35sGitD+ogSVWECjcVbHIAP
M2u9axFGlK7fDOmmkH2ZWDMtwx2I5dZps3q2g9mY2O9Az5Yokp7GW7viSpWXHTRH
xOsuY6aze71U7RWJAHUDBRA3DAEvDuwDH3697LEBAWRHAv9XXkub6mir/DCxzKI2
AE3tek40lRfU6Iukjl/uzT9GXcL3uEjIewiPTwN+k4IL+qcCEdv8WZgv/tO45r59
IZQsicNaSAsKX/6Cxha6Hosg1jw4rjdyz13rgYRi/nreq5mJAJUDBRA2r0CM9p+f
Pnxlu7UBAYObA/40s5SwEpXTrePO78AoUFEa5Z4bgyxkpT7BVbq6m/oQtK509Xe2
M2y0XTLkd86oXpjyKzGzWq8T6ZTKNdF9+5LhS2ylJytdPq1AjDk2BocffWX4+pXn
RPiC6XcNdYGiQL8OTHvZESYQDiHeMfwA8WdMzFK1R80nJMwANYXjJJrLzYkAlQMF
EDNt51zvs7EFZlNtbQEBW0UD/jZB6UDdEFdhS0hxgahv5CxaQDWQbIEpAY9JL1yg
d1RWMKUFGXdRkWZmHEA4NvtwFFeam/HZm4yuGf8yldMyo84loTcVib7lKh4CumGx
FT5Pxeh/F8u9EeQzclRFSMhVl0BA2/HEGyjw0kbkprI/RD3pXD7ewTAUrj2O3XhE
InLgiQCVAwUQM3O9vWyr6JZzEUkFAQF9nAP9Hco0V/3Kl70N5ryPVgh41nUTd7Td
6fUjx8yPoSZLX8vVZ8XMyd8ULFmzsmA+2QG4HcKo/x/4s50O3o8c+o1qSYj0Tp+K
4Z8lneMVlgBNdrRcq4ijEgk0qGqSlsXyLElkVPEXAADBVgzf6yqvipDwXNVzl6e3
GPLE8U2TAnBFZX6JAJUDBRAzZqIFDu2852ZqdCEBATsuBACI3ofP7N3xuHSc7pWL
NsnFYVEc9utBaclcagxjLLzwPKzMBcLjNGyGXIZQNB0d4//UMUJcMS7vwZ8MIton
VubbnJVHuQvENloRRARtarF+LC7OLMCORrGtbt0FtYgvBaqtgXlNcKXD6hRT+ghR
bi3q34akA7Xw8tiFIxdVgSusALQjQnJpYW4gU29tZXJzIDxicmlhbkB1ay5GcmVl
QlNELm9yZz6JAJUDBRA3FLWcnWdBAAxuEhUBAcYYBACos9nKETuaH+z2h0Ws+IIY
mN9FEm8wpPUcQmX5GFhfBUQ+rJbflzv0jJ/f2ac9qJHgIIAlJ3pMkfMpU8UYHEuo
VCe4ZTU5sr4ZdBaF9kpm2OriFgZwIv4QAi7dCMu9ZwGRtZ3+z3DQsVSagucjZTIe
yTUR6K+7E3YXANQjOdqFZYkAlQMFEDcUpeQO7bznZmp0IQEB4HED/Ru3NjwWO1gl
xEiLTzRpU31Rh1Izw1lhVMVJkLAGBw9ieSkjvdIkuhqV1i+W4wKBClT0UOE28Kjp
WbBKPFIASRYzN4ySwpprsG5H45EFQosovYG/HPcMzXU2GMj0iwVTxnMq7I8oH588
ExHqfEN2ARD3ngmB2499ruyGl26pW/BftCBCcmlhbiBTb21lcnMgPGJyaWFuQE9w
ZW5CU0Qub3JnPokAlQMFEDcUtW6dZ0EADG4SFQEBQwsD/j9B/lkltIdnQdjOqR/b
dOBgJCtUf905y6kD+k4kbxeT1YAaA65KJ2o/Zj+i+69F2+BUJ/3kYB7prKwut2h0
ek1ZtncGxoAsQdFJ5JSeMkwUZ5qtGeCmVPb59+KPq3nU6p3RI8Bn77FzK//Qy+IW
/WFVJbf/6NCNCbyRiRjPbGl/iQCVAwUQNxSlyA7tvOdmanQhAQFzMAP/dvtsj3yB
C+seiy6fB/nS+NnKBoff3Ekv57FsZraGt4z9n4sW61eywaiRzuKlhHqrDE17STKa
fBOaV1Ntl7js7og5IFPWNlVh1cK+spDmd655D8pyshziDF6fSAsqGfTn35xl23Xj
O20MMK44j4I5V6rEyUDBDrmX49J56OFkfwa0IEJyaWFuIFNvbWVycyA8YnJpYW5A
RnJlZUJTRC5vcmc+iQCVAwUQNxS1Y51nQQAMbhIVAQHPBQP+IMUlE4DtEvSZFtG4
YK9usfHSkStIafh/F/JzSsqdceLZgwcuifbemw79Rhvqhp0Cyp7kuI2kHO3a19kZ
3ZXlDl3VDg41SV/Z5LzNw9vaZKuF/vtGaktOjac5E5aznWGIA5czwsRgydEOcd8O
VPMUMrdNWRI6XROtnbZaRSwmD8aJAJUDBRA3FKWuDu2852ZqdCEBAWVJA/4x3Mje
QKV+KQoO6mOyoIcD4GK1DjWDvNHGujJbFGBmARjr/PCm2cq42cPzBxnfRhCfyEvN
aesNB0NjLjRU/m7ziyVn92flAzHqqmU36aEdqooXUY2T3vOYzo+bM7VtInarG1iU
qw1G19GgXUwUkPvy9+dNIM/aYoI/e0Iv3P9uug==
=R3k0
-----END PGP PUBLIC KEY BLOCK-----</programlisting>
</sect2>
</sect1>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->

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

@ -1,391 +0,0 @@
<!--
The FreeBSD Documentation Project
$Id: chapter.sgml,v 1.9 1999-07-28 20:23:31 nik Exp $
-->
<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>
<sect1 id="policies-maintainer">
<title><makevar>MAINTAINER</makevar> on Makefiles</title>
<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
<programlisting>
MAINTAINER= email-addresses</programlisting>
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>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
people.</para>
</sect1>
<sect1>
<title>Contributed Software</title>
<para><emphasis>Contributed by &a.phk; and &a.obrien;. </emphasis></para>
<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>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
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>
<note>
<para>Because of some unfortunate design limitations with the RCS file
format and CVS's use of vendor branches, minor, trivial and/or
cosmetic changes are <emphasis>strongly discouraged</emphasis> on
files that are still tracking the vendor branch. &ldquo;Spelling
fixes&rdquo; are explicitly included here under the
&ldquo;cosmetic&rdquo; category and are to be avoided for files with
revision 1.1.x.x. The repository bloat impact from a single character
change can be rather dramatic.</para>
</note>
<para>The <application>Tcl</application> embedded programming
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>
<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>
<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>
<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>
<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>
<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>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>
</listitem>
<listitem>
<para>Where to send patches back to the original authors</para>
</listitem>
<listitem>
<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>
<programlisting>
This directory contains virgin sources of the original distribution files
on a "vendor" branch. Do not, under any circumstances, attempt to upgrade
the files in this directory via patches and a cvs commit. New versions or
official-patch versions must be imported. Please remember to import with
"-ko" to prevent CVS from corrupting any vendor RCS Ids.
For the import of GNU cpio 2.4.2, the following files were removed:
INSTALL cpio.info mkdir.c
Makefile.in cpio.texi mkinstalldirs
To upgrade to a newer version of cpio, when it is available:
1. Unpack the new version into an empty directory.
[Do not make ANY changes to the files.]
2. Remove the files listed above and any others that don't apply to
FreeBSD.
3. Use the command:
cvs import -ko -m 'Virgin import of GNU cpio v&lt;version&gt;' \
src/contrib/cpio GNU cpio_&lt;version&gt;
For example, to do the import of version 2.4.2, I typed:
cvs import -ko -m 'Virgin import of GNU v2.4.2' \
src/contrib/cpio GNU cpio_2_4_2
4. Follow the instructions printed out in step 3 to resolve any
conflicts between local FreeBSD changes and the newer version.
Do not, under any circumstances, deviate from this procedure.
To make local changes to cpio, simply patch and commit to the main
branch (aka HEAD). Never make local changes on the GNU branch.
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-encumbered">
<title>Encumbered files</title>
<para>It might occasionally be necessary to include an encumbered file in
the FreeBSD source tree. For example, if a device requires a small
piece of binary code to be loaded to it before the device will operate,
and we do not have the source to that code, then the binary file is said
to be encumbered. The following policies apply to including encumbered
files in the FreeBSD source tree.</para>
<orderedlist>
<listitem>
<para>Any file which is interpreted or executed by the system CPU(s)
and not in source format is encumbered.</para>
</listitem>
<listitem>
<para>Any file with a license more restrictive than BSD or GNU is
encumbered.</para>
</listitem>
<listitem>
<para>A file which contains downloadable binary data for use by the
hardware is not encumbered, unless (1) or (2) apply to it. It must
be stored in an architecture neutral ASCII format (file2c or
uuencoding is recommended).</para>
</listitem>
<listitem>
<para>Any encumbered file requires specific approval from the <link
linkend="staff-core">Core team</link> before it is added to the
CVS repository.</para>
</listitem>
<listitem>
<para>Encumbered files go in <filename>src/contrib</filename> or
<filename>src/sys/contrib</filename>.</para>
</listitem>
<listitem>
<para>The entire module should be kept together. There is no point in
splitting it, unless there is code-sharing with non-encumbered
code.</para>
</listitem>
<listitem>
<para>Object files are named
<filename><replaceable>arch</replaceable>/<replaceable>filename</replaceable>.o.uu></filename>.</para>
</listitem>
<listitem>
<para>Kernel files;</para>
<orderedlist>
<listitem>
<para>Should always be referenced in
<filename>conf/files.*</filename> (for build simplicity).</para>
</listitem>
<listitem>
<para>Should always be in <filename>LINT</filename>, but the <link
linkend="staff-core">Core team</link> decides per case if it
should be commented out or not. The <link
linkend="staff-core">Core team</link> can, of course, change
their minds later on.</para>
</listitem>
<listitem>
<para>The <link linkend="staff-who">Release Engineer</link>
decides whether or not it goes in to the release.</para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>User-land files;</para>
<orderedlist>
<listitem>
<para>The <link linkend="staff-core">Core team</link> decides if
the code should be part of <command>make world</command>.</para>
</listitem>
<listitem>
<para>The <link linkend="staff-who">Release Engineer</link>
decides if it goes in to the release.</para>
</listitem>
</orderedlist>
</listitem>
</orderedlist>
</sect1>
<sect1 id="policies-shlib">
<title>Shared Libraries</title>
<para><emphasis>Contributed by &a.asami;, &a.peter;, and &a.obrien; 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>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 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>
<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>
</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>
</sect1>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->

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

File diff suppressed because it is too large Load diff

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

File diff suppressed because it is too large Load diff

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

File diff suppressed because it is too large Load diff

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

@ -1,232 +0,0 @@
<!--
The FreeBSD Documentation Project
$Id: chapter.sgml,v 1.9 1999-06-15 20:24:54 mpp Exp $
-->
<chapter id="quotas">
<title>Disk Quotas</title>
<para><emphasis>Contributed by &a.mpp;. 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>
<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>
<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>Next you will need to enable disk quotas in
<filename>/etc/sysconfig</filename>. This is done by changing the line:
<programlisting>
quotas=NO</programlisting>
to:
<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>
<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
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>
<programlisting>
/dev/da1s2g /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>
<programlisting>
/dev/da1s2g /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>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>
<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 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>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>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>
<screen>&prompt.root; <userinput>edquota -u test</userinput></screen>
<programlisting>
Quotas for user test:
/usr: blocks in use: 65, limits (soft = 50, hard = 75)
inodes in use: 7, limits (soft = 50, hard = 60)
/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:
<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>
<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>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>The following is some sample output from the <command>quota
-v</command> command for a user that has quota limits on two file
systems.</para>
<programlisting>
Disk quotas for user test (uid 1002):
Filesystem blocks quota limit grace files quota limit grace
/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>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>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->

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

File diff suppressed because it is too large Load diff

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

File diff suppressed because it is too large Load diff

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

@ -1,933 +0,0 @@
<!--
The FreeBSD Documentation Project
$Id: chapter.sgml,v 1.55 1999-08-11 13:53:13 alfred Exp $
-->
<!--
Please try to keep the CVSROOT/avail file in sync with the list of
FreeBSD developers.
-->
<chapter id="staff">
<title>FreeBSD Project Staff</title>
<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>
<para>The FreeBSD core team constitutes the project's &ldquo;Board of
Directors&rdquo;, responsible for deciding the project's overall goals
and direction as well as managing <link linkend="staff-who">specific
areas</link> of the FreeBSD project landscape.</para>
<para>(in alphabetical order by last name):</para>
<itemizedlist>
<listitem>
<para>&a.asami;</para>
</listitem>
<listitem>
<para>&a.jmb;</para>
</listitem>
<listitem>
<para>&a.ache;</para>
</listitem>
<listitem>
<para>&a.bde;</para>
</listitem>
<listitem>
<para>&a.gibbs;</para>
</listitem>
<listitem>
<para>&a.dg;</para>
</listitem>
<listitem>
<para>&a.jkh;</para>
</listitem>
<listitem>
<para>&a.phk;</para>
</listitem>
<listitem>
<para>&a.rich;</para>
</listitem>
<listitem>
<para>&a.gpalmer;</para>
</listitem>
<listitem>
<para>&a.jdp;</para>
</listitem>
<listitem>
<para>&a.dfr;</para>
</listitem>
<listitem>
<para>&a.sos;</para>
</listitem>
<listitem>
<para>&a.peter;</para>
</listitem>
<listitem>
<para>&a.wollman;</para>
</listitem>
<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>
<itemizedlist>
<listitem>
<para>&a.ugen;</para>
</listitem>
<listitem>
<para>&a.dbaker;</para>
</listitem>
<listitem>
<para>&a.mbarkah;</para>
</listitem>
<listitem>
<para>&a.stb;</para>
</listitem>
<listitem>
<para>&a.pb;</para>
</listitem>
<listitem>
<para>&a.abial;</para>
</listitem>
<listitem>
<para>&a.jb;</para>
</listitem>
<listitem>
<para>&a.torstenb;</para>
</listitem>
<listitem>
<para>&a.dburr;</para>
</listitem>
<listitem>
<para>&a.charnier;</para>
</listitem>
<listitem>
<para>&a.luoqi;</para>
</listitem>
<listitem>
<para>&a.ejc;</para>
</listitem>
<listitem>
<para>&a.kjc;</para>
</listitem>
<listitem>
<para>&a.gclarkii;</para>
</listitem>
<listitem>
<para>&a.archie;</para>
</listitem>
<listitem>
<para>&a.chris;</para>
</listitem>
<listitem>
<para>&a.alc;</para>
</listitem>
<listitem>
<para>&a.cracauer;</para>
</listitem>
<listitem>
<para>&a.adam;</para>
</listitem>
<listitem>
<para>&a.dillon;</para>
</listitem>
<listitem>
<para>&a.mdodd;</para>
</listitem>
<listitem>
<para>&a.dufault;</para>
</listitem>
<listitem>
<para>&a.uhclem;</para>
</listitem>
<listitem>
<para>&a.tegge;</para>
</listitem>
<listitem>
<para>&a.deischen;</para>
</listitem>
<listitem>
<para>&a.eivind;</para>
</listitem>
<listitem>
<para>&a.julian;</para>
</listitem>
<listitem>
<para>&a.rse;</para>
</listitem>
<listitem>
<para>&a.ru;</para>
</listitem>
<listitem>
<para>&a.se;</para>
</listitem>
<listitem>
<para>&a.jasone;</para>
</listitem>
<listitem>
<para>&a.sef;</para>
</listitem>
<listitem>
<para>&a.green;</para>
</listitem>
<listitem>
<para>&a.fenner;</para>
</listitem>
<listitem>
<para>&a.jfieber;</para>
</listitem>
<listitem>
<para>&a.jfitz;</para>
</listitem>
<listitem>
<para>&a.scrappy;</para>
</listitem>
<listitem>
<para>&a.lars;</para>
</listitem>
<listitem>
<para>&a.dirk;</para>
</listitem>
<listitem>
<para>&a.shige;</para>
</listitem>
<listitem>
<para>&a.billf;</para>
</listitem>
<listitem>
<para>&a.gallatin;</para>
</listitem>
<listitem>
<para>&a.tg;</para>
</listitem>
<listitem>
<para>&a.brandon;</para>
</listitem>
<listitem>
<para>&a.graichen;</para>
</listitem>
<listitem>
<para>&a.cg;</para>
</listitem>
<listitem>
<para>&a.jgreco;</para>
</listitem>
<listitem>
<para>&a.rgrimes;</para>
</listitem>
<listitem>
<para>&a.jmg;</para>
</listitem>
<listitem>
<para>&a.hanai;</para>
</listitem>
<listitem>
<para>&a.mharo;</para>
</listitem>
<listitem>
<para>&a.thepish;</para>
</listitem>
<listitem>
<para>&a.jhay;</para>
</listitem>
<listitem>
<para>&a.sheldonh;</para>
</listitem>
<listitem>
<para>&a.helbig;</para>
</listitem>
<listitem>
<para>&a.ghelmer;</para>
</listitem>
<listitem>
<para>&a.erich;</para>
</listitem>
<listitem>
<para>&a.nhibma;</para>
</listitem>
<listitem>
<para>&a.flathill;</para>
</listitem>
<listitem>
<para>&a.hosokawa;</para>
</listitem>
<listitem>
<para>&a.hsu;</para>
</listitem>
<listitem>
<para>&a.foxfair;</para>
</listitem>
<listitem>
<para>&a.tom;</para>
</listitem>
<listitem>
<para>&a.mph;</para>
</listitem>
<listitem>
<para>&a.shin;</para>
</listitem>
<listitem>
<para>&a.itojun;</para>
</listitem>
<listitem>
<para>&a.iwasaki;</para>
</listitem>
<listitem>
<para>&a.mjacob;</para>
</listitem>
<listitem>
<para>&a.gj;</para>
</listitem>
<listitem>
<para>&a.nsj;</para>
</listitem>
<listitem>
<para>&a.ljo;</para>
</listitem>
<listitem>
<para>&a.kato;</para>
</listitem>
<listitem>
<para>&a.andreas;</para>
</listitem>
<listitem>
<para>&a.motoyuki;</para>
</listitem>
<listitem>
<para>&a.jkoshy;</para>
</listitem>
<listitem>
<para>&a.kuriyama;</para>
</listitem>
<listitem>
<para>&a.grog;</para>
</listitem>
<listitem>
<para>&a.jlemon;</para>
</listitem>
<listitem>
<para>&a.truckman;</para>
</listitem>
<listitem>
<para>&a.lile;</para>
</listitem>
<listitem>
<para>&a.kevlo;</para>
</listitem>
<listitem>
<para>&a.imp;</para>
</listitem>
<listitem>
<para>&a.jmacd;</para>
</listitem>
<listitem>
<para>&a.smace;</para>
</listitem>
<listitem>
<para>&a.gehenna;</para>
</listitem>
<listitem>
<para>&a.mckay;</para>
</listitem>
<listitem>
<para>&a.mckusick;</para>
</listitem>
<listitem>
<para>&a.ken;</para>
</listitem>
<listitem>
<para>&a.hm;</para>
</listitem>
<listitem>
<para>&a.tedm;</para>
</listitem>
<listitem>
<para>&a.jim;</para>
</listitem>
<listitem>
<para>&a.marcel;</para>
</listitem>
<listitem>
<para>&a.amurai;</para>
</listitem>
<listitem>
<para>&a.markm;</para>
</listitem>
<listitem>
<para>&a.max;</para>
</listitem>
<listitem>
<para>&a.newton;</para>
</listitem>
<listitem>
<para>&a.rnordier;</para>
</listitem>
<listitem>
<para>&a.davidn;</para>
</listitem>
<listitem>
<para>&a.obrien;</para>
</listitem>
<listitem>
<para>&a.danny;</para>
</listitem>
<listitem>
<para>&a.ljo;</para>
</listitem>
<listitem>
<para>&a.fsmp;</para>
</listitem>
<listitem>
<para>&a.smpatel;</para>
</listitem>
<listitem>
<para>&a.wpaul;</para>
</listitem>
<listitem>
<para>&a.alfred;</para>
</listitem>
<listitem>
<para>&a.wes;</para>
</listitem>
<listitem>
<para>&a.cpiazza;</para>
</listitem>
<listitem>
<para>&a.steve;</para>
</listitem>
<listitem>
<para>&a.mpp;</para>
</listitem>
<listitem>
<para>&a.jraynard;</para>
</listitem>
<listitem>
<para>&a.darrenr;</para>
</listitem>
<listitem>
<para>&a.csgr;</para>
</listitem>
<listitem>
<para>&a.martin;</para>
</listitem>
<listitem>
<para>&a.paul;</para>
</listitem>
<listitem>
<para>&a.roberto;</para>
</listitem>
<listitem>
<para>&a.chuckr;</para>
</listitem>
<listitem>
<para>&a.guido;</para>
</listitem>
<listitem>
<para>&a.dima;</para>
</listitem>
<listitem>
<para>&a.sada;</para>
</listitem>
<listitem>
<para>&a.nsayer;</para>
</listitem>
<listitem>
<para>&a.wosch;</para>
</listitem>
<listitem>
<para>&a.ats;</para>
</listitem>
<listitem>
<para>&a.dick;</para>
</listitem>
<listitem>
<para>&a.jseger;</para>
</listitem>
<listitem>
<para>&a.simokawa;</para>
</listitem>
<listitem>
<para>&a.vanilla;</para>
</listitem>
<listitem>
<para>&a.msmith;</para>
</listitem>
<listitem>
<para>&a.des;</para>
</listitem>
<listitem>
<para>&a.brian;</para>
</listitem>
<listitem>
<para>&a.mks;</para>
</listitem>
<listitem>
<para>&a.stark;</para>
</listitem>
<listitem>
<para>&a.karl;</para>
</listitem>
<listitem>
<para>&a.sumikawa;</para>
</listitem>
<listitem>
<para>&a.nyan;</para>
</listitem>
<listitem>
<para>&a.tanimura;</para>
</listitem>
<listitem>
<para>&a.taoka;</para>
</listitem>
<listitem>
<para>&a.dt;</para>
</listitem>
<listitem>
<para>&a.cwt;</para>
</listitem>
<listitem>
<para>&a.pst;</para>
</listitem>
<listitem>
<para>&a.hoek;</para>
</listitem>
<listitem>
<para>&a.nectar;</para>
</listitem>
<listitem>
<para>&a.swallace;</para>
</listitem>
<listitem>
<para>&a.dwhite;</para>
</listitem>
<listitem>
<para>&a.nate;</para>
</listitem>
<listitem>
<para>&a.yokota;</para>
</listitem>
<listitem>
<para>&a.jmz;</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
<emphasis>deputies</emphasis> (if any):</para>
<variablelist>
<varlistentry>
<term>Documentation Project Manager</term>
<listitem>
<para>&a.nik;</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Webmaster</term>
<listitem>
<para>&a.wosch;</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Handbook &amp; FAQ Editor</term>
<listitem>
<para>&a.faq;</para>
</listitem>
</varlistentry>
<varlistentry>
<term>News Editor</term>
<listitem>
<para>&a.nsj;</para>
<para><emphasis>Deputy:</emphasis> &a.john;</para>
</listitem>
</varlistentry>
<varlistentry>
<term>In the Press Editor</term>
<listitem>
<para>&a.jkoshy</para>
</listitem>
</varlistentry>
<varlistentry>
<term>FreeBSD Really-Quick NewsLetter Editor</term>
<listitem>
<para>Chris Coleman <email>chrisc@vmunix.com</email></para>
</listitem>
</varlistentry>
<varlistentry>
<term>Gallery Editor</term>
<listitem>
<para>&a.nsj;</para>
<para><emphasis>Deputy:</emphasis> &a.cawimm;</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Commercial Editor</term>
<listitem>
<para>&a.nik;</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Web Changes Editor</term>
<listitem>
<para>-</para>
</listitem>
</varlistentry>
<varlistentry>
<term>User Groups Editor</term>
<listitem>
<para>-</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LinuxDoc to DocBook conversion</term>
<listitem>
<para>&a.nik;</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="staff-who">
<title>Who Is Responsible for What</title>
<variablelist>
<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>
<listitem>
<para>&a.nik;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><link linkend="l10n">Internationalization</link></term>
<listitem>
<para>&a.ache;</para>
</listitem>
</varlistentry>
<varlistentry><term>Networking</term>
<listitem>
<para>&a.wollman;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><link linkend="eresources-mail">Postmaster</link></term>
<listitem>
<para>&a.jmb;</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Release Coordinator</term>
<listitem>
<para>&a.jkh;</para>
</listitem>
</varlistentry>
<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>
<listitem>
<para>&a.imp;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url="http://www.FreeBSD.org/support.html#cvs">Source
Repository Managers</ulink></term>
<listitem>
<para>Principal: &a.peter;</para>
<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>
<listitem>
<para>&a.wosch;</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->

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

@ -1,25 +0,0 @@
<!--
The FreeBSD Documentation Project
$Id: chapter.sgml,v 1.5 1999-03-08 22:04:49 nik Exp $
-->
<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>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->

12
en/share/sgml/bookinfo.ent
View file

@ -1,12 +0,0 @@
<!--
References to other files that can be included within a DocBook
BookInfo element.
Entity names take the form "bookinfo.<element>", where <element> is
the name of the outermost element in the entity. Examples would
be "bookinfo.legalnotice", and "bookinfo.preface".
$Id: bookinfo.ent,v 1.1 1999-05-05 20:13:19 nik Exp $
-->
<!ENTITY bookinfo.legalnotice SYSTEM "legalnotice.sgml">

44
en/share/sgml/legalnotice.sgml
View file

@ -1,44 +0,0 @@
<!--
Standard FreeBSD Documentation Project Legal Notice.
$Id: legalnotice.sgml,v 1.1 1999-05-05 20:12:11 nik Exp $
-->
<legalnotice>
<para>Redistribution and use in source (SGML DocBook) and 'compiled'
forms (SGML, HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions are
met:</para>
<orderedlist>
<listitem>
<para>Redistributions of source code (SGML DocBook) must retain the
above copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.</para>
</listitem>
<listitem>
<para>Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must
reproduce the above copyright notice, this list of conditions and
the following disclaimer in the documentation and/or other
materials provided with the distribution.</para>
</listitem>
</orderedlist>
<important>
<para>THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION
PROJECT "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
THE FREEBSD DOCUMENTATION PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.</para>
</important>
</legalnotice>

26
en/tutorials/Makefile
View file

@ -1,26 +0,0 @@
# $Id: Makefile,v 1.18 1999-04-27 18:33:23 nik Exp $
DOCS?= index.sgml
SUBDIR= devel
SUBDIR+= diskformat
SUBDIR+= disklessx
SUBDIR+= fonts
SUBDIR+= mh
SUBDIR+= multios
SUBDIR+= newuser
DOCSUBDIR= docproj-primer
DOCSUBDIR+= ddwg
DOCSUBDIR+= ppp
SGMLOPTS+= -links -hdr ${.CURDIR}/doc.hdr -ftr ${.CURDIR}/doc.ftr
.if defined $(NEW_BUILD)
SUBDIR=
.endif
.if defined(DOCBOOK_ONLY) && !empty(DOCBOOK_ONLY)
DOCSUBDIR=
.endif
WEBBASE?= /data/
.include "../web.mk"

4
en/tutorials/Makefile.inc
View file

@ -1,4 +0,0 @@
# $Id: Makefile.inc,v 1.4 1997-07-01 03:52:21 max Exp $
WEBBASE?= /data/tutorials
SGMLOPTS+= -hdr ${.CURDIR}/../doc.hdr -ftr ${.CURDIR}/../doc.ftr

6
en/tutorials/ddwg/Makefile
View file

@ -1,6 +0,0 @@
# $Id: Makefile,v 1.3 1997-07-01 05:38:11 max Exp $
DOC= ddwg
SRCS= ddwg.sgml
.include <bsd.sgml.mk>

1243
en/tutorials/ddwg/ddwg.sgml
View file

File diff suppressed because it is too large Load diff

7
en/tutorials/devel/Makefile
View file

@ -1,7 +0,0 @@
# $Id: Makefile,v 1.4 1997-07-01 05:38:11 max Exp $
DOCS= devel.docb
INDEXLINK= devel.html
.include "../../web.mk"

1835
en/tutorials/devel/devel.docb
View file

File diff suppressed because it is too large Load diff

7
en/tutorials/diskformat/Makefile
View file

@ -1,7 +0,0 @@
# $Id: Makefile,v 1.1 1997-09-13 04:24:23 jfieber Exp $
DOCS= diskformat.docb
INDEXLINK= diskformat.html
.include "../../web.mk"

464
en/tutorials/diskformat/diskformat.docb
View file

@ -1,464 +0,0 @@
<!DOCTYPE BOOK PUBLIC "-//Davenport//DTD DocBook V3.0//EN">
<!-- $Id: diskformat.docb,v 1.5 1998-10-14 03:25:31 dwhite Exp $ -->
<book>
<bookinfo>
<bookbiblio>
<title>Formatting Media For Use With FreeBSD 2.2-RELEASE</title>
<subtitle>A Tutorial</subtitle>
<authorgroup>
<author>
<firstname>Doug</firstname>
<surname>White</surname>
<affiliation>
<address><email>dwhite@resnet.uoregon.edu</email></address>
</affiliation>
</author>
</authorgroup>
<pubdate>March 1997</pubdate>
<abstract><para>This document describes how to slice, partition, and
format hard disk drives and similar media for use with FreeBSD. The
examples given have been tested under FreeBSD 2.2-GAMMA and may work
for other releases. </para>
</abstract>
</bookbiblio>
</bookinfo>
<chapter>
<title>Introduction & Definitions</title>
<sect1>
<title>Overview</title>
<para>Successfully adding disks to an existing system is the mark of an
experienced system administrator. Slicing, partitioning, and adding
disks requires a careful dance of proper command and name syntax. One
slipped finger and an entire disk could disappear in seconds. This
document is written in an attempt to simplify this process and avoid
accidents. Thankfully, enhancements to existing tools (notably
sysinstall) have greatly improved this process in recent releases of
FreeBSD. </para>
<para>There are two possible modes of disk formatting:
<itemizedlist>
<listitem><para><firstterm>compatibility mode</firstterm>: Arranging a
disk so that it has a slice table for use with other operating
systems.</para> </listitem>
<listitem><para><firstterm>dangerously dedicated mode</firstterm>:
Formatting a disk with no slice table. This makes the process of
adding disks easier, however non-FreeBSD operating systems may not
accept the disk. </para> </listitem>
</itemizedlist>
</para>
<para>For most cases, dedicated mode is the easiest to set up and use
in existing systems, as a new disk is usually dedicated entirely to
FreeBSD. However, compatibility mode insures optimum interoperability
with future installations at a cost of increased complexity.</para>
<para>In addition to selecting the mode, two methods of slicing the
disk are available. One is using the system installation tool
<command>/stand/sysinstall</command>. 2.1.7-RELEASE and later
versions of <command>sysinstall</command> contain code to ease setup
of disks during normal system operation, mainly allowing access to the
Label and Partition editors and a Write feature which will update just
the selected disk and slice without affecting other disks. The other
method is running the tools manually from a root command line. For
dangerously dedicated mode, only three or four commands are involved
while <command>sysinstall</command> requires some manipulation.</para>
</sect1>
<sect1>
<title>Definitions</title>
<para>UNIX disk management over the centuries has invented many new
definitions for old words. The following glossary covers the
definitions used in this document and (hopefully) for FreeBSD in
general. </para>
<!-- I'm tempted to use GLOSSARY here but will resort to a list for
now. -->
<itemizedlist>
<listitem><para>compatibility mode: Arranging a disk so that it has a slice
table for use with other operating systems. Oppose dangerously
dedicated mode.</para></listitem>
<listitem><para>dangerously dedicated mode: Formatting a disk with no slice
table. This makes the process of adding disks easier, however
non-FreeBSD operating systems may not accept the disk. Oppose
compatibility mode.</para></listitem>
<listitem><para>disk: A circular disc, covered with magnetic or similarly
manipulable material, spun by a motor under a head. Data is stored on
the disk by changing the pattern of magnetism on the disc, which can
be later read. Hard disks, CD-ROMs, Magneto-optical,and Zip/Jaz
removables are examples of disks.</para></listitem>
<listitem><para>slice: A division of a disk. Up to four slices are permitted on one
disk in the PC standard. Slices are composed of contiguous sectors.
Slices are recorded in a <quote>slice table</quote> used by the system BIOS to
locate bootable partitions. The slice table is usually called the
Partition Table in DOS parlance. Maintained by the fdisk utility.</para></listitem>
<listitem><para>partition: A division of a slice. Usually used in reference
to divisions of the FreeBSD slice of a disk. Each filesystem and swap
area on a disk resides in a partition. Maintained using the disklabel
utility.</para></listitem>
<listitem><para>sector: Smallest subdivision of a disk. One sector usually
represents 512 bytes of data.</para></listitem>
</itemizedlist>
</sect1>
<sect1>
<title>Warnings & Pitfalls</title>
<para>Building disks is not something to take lightly. It is quite possible
to destroy the contents of other disks in your system if the proper
precautions are not taken.</para>
<para><emphasis>Check your work carefully.</> It is very simple to destroy
the incorrect disk when working with these commands. When
in doubt consult the kernel boot output for the proper device.</para>
<para>Needless to say, we are not responsible for any damage to any data
or hardware that you may experience. You work at your own risk!</para>
</sect1>
<sect1>
<title>Zip, Jaz, and Other Removables</title>
<para>Removable disks can be formatted in the same way as normal hard
disks. It is essential to have the disk drive connected to the system
and a disk placed in the drive during startup, so the kernel can
determine the drive's geometry. Check the <command>dmesg</command>
output and make sure your device and the disk's size is listed. If
the kernel reports
<informalexample>
<screen>
Can't get the size
</screen>
</informalexample>
then the disk was not in the drive. In this case, you will need to restart the
machine before attempting to format disks.
</para>
</sect1>
</chapter>
<chapter>
<title>Formatting Disks in Dedicated Mode</title>
<sect1>
<title>Introduction</title>
<para>This section details how to make disks that are totally dedicated to
FreeBSD. Remember, dedicated mode disks cannot be booted by the PC
architecture.</para>
</sect1>
<sect1>
<title>Making Dedicated Mode Disks using Sysinstall</title>
<para><command>/stand/sysinstall</command>, the system installation
utility, has been expanded in recent versions to make the process of
dividing disks properly a less tiring affair. The fdisk and disklabel
editors built into sysinstall are GUI tools that remove much of the
confusion from slicing disks. For FreeBSD versions 2.1.7 and later,
this is perhaps the simplest way to slice disks.</para>
<orderedlist>
<listitem><para>Start sysinstall as root by typing
<informalexample>
<screen><userinput>/stand/sysinstall</userinput></screen>
</informalexample>
from the command prompt.</para></listitem>
<listitem><para>Select <command>Index</command>.</para></listitem>
<listitem><para>Select <command>Partition</command>.</para></listitem>
<listitem><para>Select the disk to edit with arrow keys and
<keycap>SPACE</keycap>.</para>
</listitem>
<listitem><para>If you are using this entire disk for FreeBSD, select
<command>A</command>.</para></listitem>
<listitem><para>When asked:
<informalexample>
<screen>
Do you want to do this with a true partition entry so as to remain
cooperative with any future possible operating systems on the
drive(s)?
</screen>
</informalexample>answer <command>No</command>.</para></listitem>
<listitem><para>When asked if you still want to do this, answer
<command>Yes</command>.</para></listitem>
<listitem><para>Select <command>Write</command>.</para></listitem>
<listitem><para>When warned about Writing on installed systems, answer
<command>Yes</command>.</para></listitem>
<listitem><para><command>Quit</command>the FDISK Editor and
<keycap>ESCAPE</keycap> back to the Index menu.</para></listitem>
<listitem><para>Select <command>Label</command> from the Index
menu.</para></listitem>
<listitem><para>Label as desired. For a single partition, enter
<command>C</command> to Create a partition, accept the
default size, partition type Filesystem, and a mountpoint (which isn't
used).</para></listitem>
<listitem><para>Enter <command>W</command> when done and confirm to
continue. The filesystem will be newfs'd for you, unless you select
otherwise (for news partitions you'll want to do this!). You'll get
the error:
<informalexample>
<screen>Error mounting /mnt/dev/wd2s1e on /mnt/blah : No such file or directory </screen>
</informalexample>
Ignore.
</para></listitem>
<listitem><para>Exit out by repeatedly pressing <keycap>ESCAPE</keycap>.</para></listitem>
</orderedlist>
</sect1>
<sect1>
<title>Making Dedicated Mode Disks Using the Command Line</title>
<para>Execute the following commands, replacing wd2 with the disk
name. Lines beginning with # are comments. </para>
<informalexample>
<screen>
<userinput>
dd if=/dev/zero of=/dev/rwd2 count=2
disklabel /dev/rwd2 | disklabel -B -R -r wd2 /dev/stdin
# We only want one partition, so using slice 'c' should be fine:
newfs /dev/rwd2c
</userinput>
</screen>
</informalexample>
<para> If you need to edit the disklabel to create multiple
partitions (such as swap), use the following: </para>
<informalexample>
<screen>
<userinput>
dd if=/dev/zero of=/dev/rwd2 count=2
disklabel /dev/r$d > /tmp/label
# Edit disklabel to add partitions:
vi /tmp/label
disklabel -B -R -r wd2 /tmp/label
# newfs partitions appropriately
</userinput>
</screen>
</informalexample>
<para>Your disk is now ready for use.</para>
</sect1>
</chapter>
<chapter>
<title>Making Compatibility Mode Disks</title>
<sect1>
<title>Introduction</title>
<para>The command line is the easiest way to make dedicated disks, and
the worst way to make compatibility disks. The command-line fdisk
utility requires higher math skills and an in-depth understanding of
the slice table, which is more than most people want to deal with.
Use sysinstall for compatibility disks, as described below.</para>
</sect1>
<sect1>
<title>Making Compatibility Mode Disks Using Sysinstall</title>
<orderedlist>
<listitem><para>Start sysinstall as root by typing
<informalexample>
<screen><userinput>/stand/sysinstall</></screen>
</informalexample>
from the command prompt.</para></listitem>
<listitem><para>Select <command>Index</command>.</para> </listitem>
<listitem><para>Select <command>Partition</command>.</para></listitem>
<listitem><para>Select the disk to edit with arrow keys and
<keycap>SPACE</keycap>.
</para></listitem>
<listitem><para>If you are using this entire disk for FreeBSD, select
<command>A</command>.</para></listitem>
<listitem><para>When asked:
<informalexample>
<screen>
Do you want to do this with a true partition entry so as to remain
cooperative with any future possible operating systems on the
drive(s)?
</screen>
</informalexample> answer <command>yes</command>.</para></listitem>
<listitem><para>Select <command>Write</command>.</para></listitem>
<listitem><para>When asked to install the boot manager, select None with
<keycap>SPACE</keycap> then hit <keycap>ENTER</keycap> for OK.</para></listitem>
<listitem><para><command>Quit</command> the FDISK Editor.</para></listitem>
<listitem><para>You'll be asked about the boot manager, select
<command>None</command>
again. </para></listitem>
<listitem><para>Select <command>Label</command> from the Index
menu.</para></listitem>
<listitem><para>Label as desired. For a single partition, accept the
default size, type filesystem, and a mountpoint (which isn't
used).</para></listitem>
<listitem><para>The filesystem will be newfs'd for you, unless you select otherwise (for news partitions you'll want to do this!). You'll get the error:
<informalexample>
<screen>
Error mounting /mnt/dev/wd2s1e on /mnt/blah : No such file or directory </screen>
</informalexample>
Ignore.
</para></listitem>
<listitem><para>Exit out by repeatedly pressing <keycap>ESCAPE</keycap>.</para></listitem>
</orderedlist>
<para>Your new disk is now ready for use.</para>
</sect1>
</chapter>
<chapter>
<title>Other Disk Operations</title>
<sect1>
<title>Adding Swap Space</title>
<para>As a system grows, it's need for swap space can also grow.
Although adding swap space to existing disks is very difficult, a new
disk can be partitioned with additional swap space. </para>
<para>To add swap space when adding a disk to a system:
<orderedlist>
<listitem><para>When partitioning the disk, edit the disklabel and
allocate the amount of swap space to add in partition `b' and the
remainder in another partition, such as `a' or `e'. The size is given
in 512 byte blocks. </para></listitem>
<listitem><para>When newfsing the drive, do NOT newfs the `c'
partition. Instead, newfs the partition where the non-swap space
lies.</para></listitem>
<listitem><para>Add an entry to <filename>/etc/fstab</filename> as follows:
<informalexample>
<programlisting>
/dev/wd0b none swap sw 0 0
</programlisting>
</informalexample>
Change /dev/wd0b to the device of the newly added
space.</para></listitem>
<listitem><para>To make the new space immediately available, use the
<command>swapon</command> command.
<informalexample>
<screen>
<userinput>
$ swapon /dev/sd0b
</userinput>
swapon: added /dev/sd0b as swap space
</screen>
</informalexample>
</para></listitem>
</orderedlist>
</para>
</sect1>
<sect1>
<title>Copying the Contents of Disks</title>
<!-- Should have specific tag -->
<para>Submitted By: Renaud Waldura (<email>renaud@softway.com</email>) </para>
<para>To move file from your original base disk to the fresh new one,
do:
<informalexample>
<screen>
<userinput>
mount /dev/wd2 /mnt
pax -r -w -p e /usr/home /mnt
umount /mnt
rm -rf /usr/home/*
mount /dev/wd2 /usr/home
</userinput>
</screen>
</informalexample>
</para>
</sect1>
<sect1>
<title>Creating Striped Disks using CCD</title>
<para>Commands Submitted By: Stan Brown (<email>stanb@awod.com</email>) </para>
<para>
The Concatenated Disk Driver, or CCD, allows you to treat several identical disks as a single disk.
Striping can result in increased disk performance by distributing reads and
writes across the disks. See the ccd(4) and ccdconfig(4) man pages or the
<ulink URL="http://stampede.cs.berkeley.edu/ccd/">CCD Homepage</ulink> for further details.</para>
<para>To create a new CCD, execute the following commands. This describes
how to add three disks together; simply add or remove devices as
necessary. Remember that the disks to be striped must be <emphasis>identical.</></para>
<para>Before executing these commands, make sure you add the line
<userinput>
pseudo-device ccd 4
</userinput>
to your kernel.</para>
<informalexample>
<screen>
<userinput>
cd /dev ; sh MAKDEV ccd0
disklabel -r -w sd0 auto
disklabel -r -w sd1 auto
disklabel -r -w sd2 auto
disklabel -e sd0c # change type to 4.2BSD
disklabel -e sd1c # change type to 4.2BSD
disklabel -e sd2c # change type to 4.2BSD
ccdconfig ccd0 32 0 /dev/sd0c /dev/sd1c /dev/sd2c
newfs /dev/rccd0c
</userinput>
</screen>
</informalexample>
<para>Now you can mount and use your CCD by referencing device /dev/ccd0c.
</para>
</sect1>
</chapter>
<chapter>
<title>Credits</title>
<para>The author would like to thank the following individuals for
their contributions to this project:
<itemizedlist>
<listitem><para>Darryl Okahata
(<email>darrylo@hpnmhjw.sr.hp.com</email>) for his
simple dedicated mode setup documentation which I have used repeatedly
on freebsd-questions.</para></listitem>
<listitem><para>Jordan Hubbard
(<email>jkh@freebsd.org</email>) for making
sysinstall useful for this type of task.</para></listitem>
<listitem><para>John Fieber
(<email>jfieber@indiana.edu</email>) for making
information and examples of the DocBook DTD on which this document is
based.</para></listitem>
<listitem><para>Greg Lehey (<email>grog@freebsd.org</email>) for checking my
work and pointing out inaccuracies, as well as miscellaneous support.
</para></listitem>
</itemizedlist>
</para>
</chapter>
</book>

5
en/tutorials/disklessx/Makefile
View file

@ -1,5 +0,0 @@
# $Id: Makefile,v 1.3 1998-08-24 23:43:17 wosch Exp $
DOCS= disklessx.docb
.include "../../web.mk"

287
en/tutorials/disklessx/disklessx.docb
View file

@ -1,287 +0,0 @@
<!-- $Id: disklessx.docb,v 1.1 1998-08-24 23:43:17 wosch Exp $ -->
<!-- The FreeBSD Documentation Project -->
<!DOCTYPE BOOK PUBLIC "-//Davenport//DTD DocBook V3.0//EN">
<book>
<bookinfo>
<bookbiblio>
<title>Diskless X Server: a how to guide</title>
<authorgroup>
<author>
<firstname> Jerry</firstname>
<surname>Kendall</surname>
<affiliation>
<address>
<email>jerry@kcis.com</email>
</address>
</affiliation>
</author></authorgroup>
<pubdate>28-December-1996</pubdate>
<copyright>
<year>1996</year>
<holder>Jerry Kendall</holder>
</copyright>
<abstract><para>
With the help of some 'friends' on the FreeBSD-hackers list, I have
been able to create a diskless X terminal... The creation of the X terminal
required first creating a diskless system with minimal utilities mounted
via NFS. These same steps were used to create 2 separate diskless systems.
The first is 'altair.kcis.com'. A diskless X terminal that I run on my
old 386DX-40. It has a 340Meg hard disk but, I did not want to change it.
So, it boots from 'antares.kcis.com' across a Ethernet. The second system
is a 486DX2-66. I setup a diskless FreeBSD (complete) that uses no local
disk. The server in that case is a Sun 670MP running
SunOS 4.1.3. The same setup configuration was needed for both.
</para>
<para>
NOTE: I am sure that there is stuff that needs to be added to this. Please send me any comments....
</para>
</abstract>
</bookbiblio>
</bookinfo>
<chapter><title>Creating the boot floppy (On the diskless system)</title>
<para>Since the network boot loaders will not work with some of
the TSR's and such that MS-DOS uses, it is best to create
a dedicated boot floppy OR, if you can, create an MS-DOS menu
that will (via the config.sys/autoexec.bat files) ask what
configuration to load when the system starts. The later is the
method that I use and it works great. My MS-DOS (6.x) menu is below.</para>
<informalexample><screen>
---- config.sys ----
[menu]
menuitem=normal, normal
menuitem=unix, unix
[normal]
....
normal config.sys stuff
...
[unix]
----
---- autoexec.bat ----
@ECHO OFF
goto %config%
:normal
...
normal autoexec.bat stuff
...
goto end
:unix
cd \netboot
nb8390.com
:end
----
</screen></informalexample>
</chapter>
<chapter><title>Getting the network boot programs (On the server)</title>
<para>Compile the 'net-boot' programs that are located in
/usr/src/sys/i386/boot/netboot. You should read the comments
at the top of the makefile. Adjust as required. !!!! make a
backup of the original in case it gets fobar'd !!! When the build
is done, there should be 2 MS-DOS executables, 'nb8390.com' and
'nb3c509.com'. One of these two programs will be what you need
to run on the diskless server. It will load the kernel from the
boot server. At this point, put both programs on the MS-DOS
boot floppy created earlier.</para>
</chapter>
<chapter><title>Determine which program to run (On the diskless system)</title>
<para>If you know the chipset that your Ethernet adapter uses, this is
easy. If you have the NS8390 chipset, or a NS8390 based chipset,
use NB8390.COM. If you have a 3Com 509 based chipset, use the
NB3C509.COM boot program. If you are not sure which you have,
try using one, if it says 'No adapter found', try the other.
Beyond that, you are pretty much on your own.</para>
</chapter>
<chapter><title>Booting across the network</title>
<para>Boot the diskless system with out any config.sys/autoexec.bat
files. try running the boot program for your Ethernet adapter.</para>
<informalexample><screen>
My Ethernet adapter is running in WD8013 16bit mode so
I run NB8390.COM
C:> cd \netboot
C:> nb8390
Boot from Network (Y/N) ? Y
BOOTP/TFTP/NFS bootstrap loader ESC for menu
Searching for adapter..
WD8013EBT base 0x0300, memory 0x000D8000, addr 00:40:01:43:26:66
Searching for server..</screen></informalexample>
<para>At this point, my diskless system is trying to find a machine to act
as a boot server. Make note of the addr line above, you will need this
number later. Reset the diskless system and modify your config.sys and
autoexec.bat files to do these steps automatically for you. Perhaps in
a menu. If you had to run 'nb3c509.com' instead of 'nb8390.com' the
output is the same as above. If you got 'No adapter found' at the
'Searching for adapter..' message, verify that you did indeed set the
compile time defines in the makefile correctly.</para>
</chapter>
<chapter><title>Allowing systems to boot across the network (On the
server)</title>
<para>Make sure the /etc/inetd.conf file has entries for tftp and bootps.
Mine are listed below:</para>
<informalexample><screen>
---- /etc/inetd.conf ----
tftp dgram udp wait nobody /usr/libexec/tftpd tftpd
#
# Additions by who ever you are
bootps dgram udp wait root /usr/libexec/bootpd bootpd /etc/bootptab
----
</screen></informalexample>
<para>If you have to change the /etc/inetd.conf file, send a HUP signal to
inetd. To do this, get the process ID of inetd with 'ps -ax | grep
inetd | grep -v grep'. Once you have it, send it a HUP signal. Do this
by 'kill -HUP &lt;pid&gt;'. This will force inetd to re-read its config file.</para>
<para>Did you remember to note the 'addr' line from the output of the boot
loader on the diskless system???? Guess what, here is where you need it.</para>
<para>Add an entry to /etc/bootptab (maybe creating the file). It should be
laid out identical to this:</para>
<informalexample><screen>
altair:\
:ht=ether:\
:ha=004001432666:\
:sm=255.255.255.0:\
:hn:\
:ds=199.246.76.1:\
:ip=199.246.76.2:\
:gw=199.246.76.1:\
:vm=rfc1048:
The lines are as follows:
'altair' the diskless systems name without the domain name.
'ht=ether' the hardware type of 'ethernet'.
'ha=004001432666' the hardware address (the number noted above).
'sm=255.255.255.0' the subnet mask.
'hn' tells server to send client's hostname to the client.
'ds=199.246.76.1' tells the client who the domain server is.
'ip=199.246.76.2' tells the client what it's IP address is.
'gw=199.246.76.1' tells the client what the default gateway is.
'vm=...' just leave it there...
</screen></informalexample>
<para>NOTE:
****** Be sure to setup the IP addresses correctly, the addresses
above are my own......</para>
<para>Create the directory '/tftpboot' on the server it will contain the
configuration files for the diskless systems that the server will
serve. These files will be named 'cfg.&lt;ip&gt;' where &lt;ip&gt; is the IP
address of the diskless system. The config file for 'altair' is
/tftpboot/cfg.199.246.76.2. The contents is:</para>
<informalexample><screen>
---- /tftpboot/cfg.199.246.76.2 ----
rootfs 199.246.76.1:/DiskLess/rootfs/altair
hostname altair.kcis.com
----
</screen></informalexample>
<para>The line 'hostname altair.kcis.com' simply tells the diskless
system what its fully qualified domain name is.</para>
<para>The line 'rootfs 199.246.76.1:/DiskLess/rootfs/altair' tells the
diskless system where its NFS mountable root filesystem is located.</para>
<para>NOTE:!!!!! The NFS mounted root filesystem will be mounted READ ONLY.</para>
<para>The hierarchy for the diskless system can be re-mounted allowing
read-write operations if required.</para>
<para>I use my spare 386DX-40 as a dedicated X terminal...</para>
<para>The hierarchy for 'altair' is:</para>
<informalexample><screen>
/
/bin
/etc
/tmp
/sbin
/dev
/dev/fd
/usr
/var
/var/run
</screen></informalexample>
<para>The actual list of files is:</para>
<informalexample><screen>
-r-xr-xr-x 1 root wheel 779984 Dec 11 23:44 ./kernel
-r-xr-xr-x 1 root bin 299008 Dec 12 00:22 ./bin/sh
-rw-r--r-- 1 root wheel 499 Dec 15 15:54 ./etc/rc
-rw-r--r-- 1 root wheel 1411 Dec 11 23:19 ./etc/ttys
-rw-r--r-- 1 root wheel 157 Dec 15 15:42 ./etc/hosts
-rw-r--r-- 1 root bin 1569 Dec 15 15:26 ./etc/XF86Config.altair
-r-x------ 1 bin bin 151552 Jun 10 1995 ./sbin/init
-r-xr-xr-x 1 bin bin 176128 Jun 10 1995 ./sbin/ifconfig
-r-xr-xr-x 1 bin bin 110592 Jun 10 1995 ./sbin/mount_nfs
-r-xr-xr-x 1 bin bin 135168 Jun 10 1995 ./sbin/reboot
-r-xr-xr-x 1 root bin 73728 Dec 13 22:38 ./sbin/mount
-r-xr-xr-x 1 root wheel 1992 Jun 10 1995 ./dev/MAKEDEV.local
-r-xr-xr-x 1 root wheel 24419 Jun 10 1995 ./dev/MAKEDEV
</screen></informalexample>
<para>Don't forget to 'MAKEDEV all' in the 'dev' directory.</para>
<para>My /etc/rc for 'altair' is:</para>
<informalexample><screen>
#!/bin/sh
#
PATH=/bin:/sbin
export PATH
#
# configure the localhost
/sbin/ifconfig lo0 127.0.0.1
#
# configure the ethernet card
/sbin/ifconfig ed0 199.246.76.2 netmask 0xffffff00
#
# mount the root filesystem via NFS
/sbin/mount antares:/DiskLess/rootfs/altair /
#
# mount the /usr filesystem via NFS
/sbin/mount antares:/DiskLess/usr /usr
#
/usr/X11R6/bin/XF86_SVGA -query antares -xf86config /etc/XF86Config.altair > /dev/null 2>&1
#
# Reboot after X exits
/sbin/reboot
#
# We blew up....
exit 1
</screen></informalexample>
<para>Any comments and ALL questions welcome....</para>
</chapter>
</book>

5
en/tutorials/doc.ftr
View file

@ -1,5 +0,0 @@
<hr>
<address>
<a href="../../mailto.html">freebsd-questions@freebsd.org</a>
</address>

14
en/tutorials/doc.hdr
View file

@ -1,14 +0,0 @@
<IMG SRC="../../gifs/bar.gif" ALT="" WIDTH="565" HEIGHT="33" BORDER=0 usemap="#bar">
<map name="bar">
<area shape="rect" coords="1,1,111,31" href="../../index.html" ALT="">
<area shape="rect" coords="112,11,196,31" href="../../ports/index.html" ALT="">
<area shape="rect" coords="196,12,257,33" href="../../support.html" ALT="">
<area shape="rect" coords="256,12,365,33" href="../../docs.html" ALT="">
<area shape="rect" coords="366,13,424,32" href="../../commercial/commercial.html" ALT="">
<area shape="rect" coords="425,16,475,32" href="../../search/search.html" ALT="">
<area shape="rect" coords="477,16,516,33" href="../../search/index-site.html" ALT="">
<area shape="rect" coords="516,15,562,33" href="../../index.html" ALT="">
<area shape="rect" href="../../index.html" coords="0,0,564,32" ALT="">
</map>
<br clear=all>

41
en/tutorials/docproj-primer/Makefile
View file

@ -1,41 +0,0 @@
#
# $Id: Makefile,v 1.3 1999-07-14 22:31:29 nik Exp $
#
# Build the FreeBSD Documentation Project Primer.
#
MAINTAINER=nik@FreeBSD.ORG
DOC?= book
FORMATS?= html-split html
INSTALL_COMPRESSED?= gz
INSTALL_ONLY_COMPRESSED?=
#
# SRCS lists the individual SGML files that make up the document. Changes
# to any of these files will force a rebuild
#
# SGML content
SRCS= book.sgml
SRCS+= overview/chapter.sgml
SRCS+= psgml-mode/chapter.sgml
SRCS+= see-also/chapter.sgml
SRCS+= sgml-markup/chapter.sgml
SRCS+= sgml-primer/chapter.sgml
SRCS+= stylesheets/chapter.sgml
SRCS+= the-faq/chapter.sgml
SRCS+= the-handbook/chapter.sgml
SRCS+= the-website/chapter.sgml
SRCS+= tools/chapter.sgml
SRCS+= translations/chapter.sgml
SRCS+= writing-style/chapter.sgml
# Entities
SRCS+= chapters.ent
DOC_PREFIX?= ../../..
.include "../../../share/mk/docproj.docbook.mk"

281
en/tutorials/docproj-primer/book.sgml
View file

@ -1,281 +0,0 @@
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML, HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
$Id: book.sgml,v 1.5 1999-07-14 22:31:28 nik Exp $
-->
<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [
<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
%man;
<!ENTITY % chapters SYSTEM "chapters.ent"> %chapters;
]>
<book>
<bookinfo>
<title>FreeBSD Documentation Project Primer for New Contributors</title>
<author>
<firstname>Nik</firstname>
<surname>Clayton</surname>
<affiliation>
<address><email>nik@FreeBSD.ORG</email></address>
</affiliation>
</author>
<copyright>
<year>1998</year>
<year>1999</year>
<holder role="mailto:nik@FreeBSD.ORG">Nik Clayton</holder>
</copyright>
<pubdate role="rcs">$Date: 1999-07-14 22:31:28 $</pubdate>
<releaseinfo>$Id: book.sgml,v 1.5 1999-07-14 22:31:28 nik Exp $</releaseinfo>
<legalnotice>
<para>Redistribution and use in source (SGML DocBook) and 'compiled'
forms (SGML, HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions are
met:</para>
<orderedlist>
<listitem>
<para>Redistributions of source code (SGML DocBook) must retain the
above copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.</para>
</listitem>
<listitem>
<para>Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must
reproduce the above copyright notice, this list of conditions and
the following disclaimer in the documentation and/or other
materials provided with the distribution.</para>
</listitem>
</orderedlist>
<important>
<para>THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.</para>
</important>
</legalnotice>
<abstract>
<para>Thank you for becoming a part of the FreeBSD Documentation
Project. Your contribution is extremely valuable.</para>
<para>This primer covers everything you will need to know in order
to start contributing to the FreeBSD Documentation Project, from
the tools and software you will be using (both mandatory and
recommended) to the philosophy behind the Documentation
Project.</para>
<para>This document is a work in progress, and is not complete. Sections
that are known to be incomplete are indicated with a
<literal>*</literal> in their name.</para>
</abstract>
</bookinfo>
<preface>
<title>Preface</title>
<sect1>
<title>Shell Prompts</title>
<para>The following table shows the default system prompt and superuser
prompt. The examples will use this prompt to indicate which user you
should be running the example as.</para>
<informaltable frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>User</entry>
<entry>Prompt</entry>
</row>
</thead>
<tbody>
<row>
<entry>Normal user</entry>
<entry>&prompt.user;</entry>
</row>
<row>
<entry><username>root</username></entry>
<entry>&prompt.root;</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect1>
<sect1>
<title>Typographic Conventions</title>
<para>The following table describes the typographic conventions used in
this book.</para>
<informaltable frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Meaning</entry>
<entry>Examples</entry>
</row>
</thead>
<tbody>
<row>
<entry>The name of commands, files, and directories. On screen
computer output.</entry>
<entry><para>Edit your <filename>.login</filename>
file.</para><para>Use <command>ls -a</command> to list all
files.</para><para><screen>You have mail.</screen>
</para></entry>
</row>
<row>
<entry>What you type, when contrasted with on-screen computer
output.</entry>
<entry><screen>&prompt.user; <userinput>su</userinput>
Password:</screen></entry>
</row>
<row>
<entry>Manual page references.</entry>
<entry>Use <citerefentry>
<refentrytitle>su</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry> to change user names.</entry>
</row>
<row>
<entry>User and group names</entry>
<entry>Only <username>root</username> can do this.</entry>
</row>
<row>
<entry>Emphasis</entry>
<entry>You <emphasis>must</emphasis> do this.</entry>
</row>
<row>
<entry>Command line variables; replace with the real name or
variable.</entry>
<entry>To delete a file, type <command>rm <filename><replaceable>filename</replaceable></filename></command></entry>
</row>
<row>
<entry>Environment variables</entry>
<entry><envar>$HOME</envar> is your home directory.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect1>
<sect1>
<title>Notes, warnings, and examples</title>
<para>Within the text appear notes, warnings, and examples.</para>
<note>
<para>Notes are represented like this, and contain information that
you should take note of, as it may affect what you do.</para>
</note>
<warning>
<para>Warnings are represented like this, and contain information
warning you about possible damage if you do not follow the
instructions. This damage may be physical, to your hardware or to
you, or it may be non-physical, such as the inadvertant deletion of
important files.</para>
</warning>
<example>
<title>A sample example</title>
<para>Examples are represented like this, and typically contain
examples you should walk through, or show you what the results of a
particular action should be.</para>
</example>
</sect1>
<sect1>
<title>Acknowledgments</title>
<para>My thanks to Sue Blake, Patrick Durusau, Jon Hamilton, Peter
Flynn, and Christopher Maden, who took the time to read early drafts
of this document and offer many valuable comments and
criticisms.</para>
</sect1>
</preface>
&chap.overview;
&chap.tools;
&chap.sgml-primer;
&chap.sgml-markup;
&chap.stylesheets;
&chap.the-faq;
&chap.the-handbook;
&chap.the-website;
&chap.translations;
&chap.writing-style;
&chap.psgml-mode;
&chap.see-also;
</book>
<!--
Local Variables:
mode: sgml
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
End:
-->

1
en/tutorials/docproj-primer/chapter.decl
View file

@ -1 +0,0 @@
<!DOCTYPE chapter PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN">

23
en/tutorials/docproj-primer/chapters.ent
View file

@ -1,23 +0,0 @@
<!--
Creates entities for each chapter in the Documentation Project Primer.
Each entity is named chap.foo, where foo is the value of the id
attribute on that chapter, and corresponds to the name of the
directory in which that chapter's .sgml file is stored.
Chapters should be listed in the order in which they are referenced.
$Id: chapters.ent,v 1.2 1999-07-14 22:31:29 nik Exp $
-->
<!ENTITY chap.overview SYSTEM "overview/chapter.sgml">
<!ENTITY chap.sgml-primer SYSTEM "sgml-primer/chapter.sgml">
<!ENTITY chap.tools SYSTEM "tools/chapter.sgml">
<!ENTITY chap.sgml-markup SYSTEM "sgml-markup/chapter.sgml">
<!ENTITY chap.stylesheets SYSTEM "stylesheets/chapter.sgml">
<!ENTITY chap.the-faq SYSTEM "the-faq/chapter.sgml">
<!ENTITY chap.the-handbook SYSTEM "the-handbook/chapter.sgml">
<!ENTITY chap.the-website SYSTEM "the-website/chapter.sgml">
<!ENTITY chap.translations SYSTEM "translations/chapter.sgml">
<!ENTITY chap.writing-style SYSTEM "writing-style/chapter.sgml">
<!ENTITY chap.psgml-mode SYSTEM "psgml-mode/chapter.sgml">
<!ENTITY chap.see-also SYSTEM "see-also/chapter.sgml">

179
en/tutorials/docproj-primer/overview/chapter.sgml
View file

@ -1,179 +0,0 @@
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
$Id: chapter.sgml,v 1.2 1999-07-14 19:25:40 nik Exp $
-->
<chapter id="overview">
<title>Overview</title>
<para>Welcome to the FreeBSD Documentation Project. Good quality
documentation is very important to the success of FreeBSD, and the
FreeBSD Documentation Project (FDP) is how a lot of that documentation
is produced. Your contributions are very valuable.</para>
<para>This document's main purpose is to clearly explain <emphasis>how
the FDP is organised</emphasis>, <emphasis>how to write and submit
documentation to the FDP</emphasis>, and <emphasis>how to
effectively use the tools available to you when writing
documentation</emphasis>.</para>
<para>Every one is welcome to join the FDP. There is no minimum
membership requirements, no quota of documentation you need to
produce per month. All you need to do is subscribe to the
<email>freebsd-doc@freebsd.org</email> mailing list.</para>
<para>After you have finished reading this document you should:</para>
<itemizedlist>
<listitem>
<para>Know which documentation is maintained by the FDP.</para>
</listitem>
<listitem>
<para>Be able to read and understand the SGML source code for the
documentation maintained by the FDP.</para>
</listitem>
<listitem>
<para>Be able to make changes to the documentation.</para>
</listitem>
<listitem>
<para>Be able to submit your changes back for review and eventual
inclusion in the FreeBSD documentation.</para>
</listitem>
</itemizedlist>
<sect1>
<title>The FreeBSD Documentation Set</title>
<para>The FDP is responsible for four categories of FreeBSD
documentation.</para>
<variablelist>
<varlistentry>
<term>Manual pages</term>
<listitem>
<para>The English language system manual pages are not written by
the FDP, as they are part of the base system. However, the FDP can
(and has) re-worded parts of existing manual pages to make them
clearer, or to correct inaccuracies.</para>
<para>The translation teams are responsible for translating the
system manual pages in to different languages. These translations
are kept within the FDP.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>FAQ</term>
<listitem>
<para>The FAQ aims to address (in short question and answer format)
questions that are asked, or should be asked, on the various
mailing lists and newsgroups devoted to FreeBSD. The format does
not permit long and comprehensive answers.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Handbook</term>
<listitem>
<para>The Handbook aims to be the comprehensive on-line resource and
reference for FreeBSD users.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Web site</term>
<listitem>
<para>This is the main FreeBSD presence on the World Wide Web,
visible at <ulink
url="http://www.freebsd.org/">http://www.freebsd.org/</ulink>
and many mirrors around the world. The web site is many people's
first exposure to FreeBSD.</para>
</listitem>
</varlistentry>
</variablelist>
<para>These four groups of documentation are all available in the
FreeBSD CVS tree. This means that the logs and changes to these
files are visible to anyone, and anyone can use a program such as
<application>CVSup</application> or
<application>CTM</application> to keep their own local copies of
this documentation.</para>
<para>In addition, many people have written tutorials or other web
sites relating to FreeBSD. Some of these are stored in the CVS
repository as well (where the author has agreed to this). In
other cases the author has decided to keep their documentation
separate from the main FreeBSD repository. The FDP endeavours to
provide links to as much of this documentation as
possible.</para>
</sect1>
<sect1>
<title>Before you start</title>
<para>This document assumes that you already know:</para>
<itemizedlist>
<listitem>
<para>How to maintain an up-to-date local copy of the FreeBSD
documentation. Either by maintaining a local copy of the
FreeBSD CVS repository (using <application>CVS</application>
and either <application>CVSup</application> or
<application>CTM</application>) or by using
<application>CVSup</application> to download just a
<emphasis>checked-out</emphasis> copy.</para>
</listitem>
<listitem>
<para>How to download and install new software using either the
FreeBSD Ports system or &man.pkg.add.1;.</para>
</listitem>
</itemizedlist>
</sect1>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../book.sgml" "part" "chapter")
End:
-->

150
en/tutorials/docproj-primer/psgml-mode/chapter.sgml
View file

@ -1,150 +0,0 @@
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
$Id: chapter.sgml,v 1.2 1999-07-14 19:17:50 nik Exp $
-->
<chapter id="psgml-mode">
<title>Using <literal>sgml-mode</literal> with
<application>Emacs</application></title>
<para>Recent versions of Emacs or Xemacs (available from the ports
collection) contain a very useful package called PSGML. Automatically
invoked when a file with <filename>.sgml</filename> extension is loaded,
or by typing <command>M-x sgml-mode</command>, it is a major mode for
dealing with SGML files, elements and attributes.</para>
<para>An understanding of some of the commands provided by this mode can
make working with SGML documents such as the Handbook much easier.</para>
<variablelist>
<varlistentry>
<term><command>C-c C-e</command></term>
<listitem>
<para>Runs <literal>sgml-insert-element</literal>. You will be
prompted for the name of the element to insert at the current point.
You can use the TAB key to complete the element. Elements that are
not valid at the current point will be disallowed.</para>
<para>The start and end tags for the element will be inserted. If the
element contains other, mandatory, elements then these will be
inserted as well.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>C-c =</command></term>
<listitem>
<para>Runs <literal>sgml-change-element-name</literal>. Place the
point within an element and run this command. You will be prompted
for the name of the element to change to. Both the start and end
tags of the current element will be changed to the new
element.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>C-c C-r</command></term>
<listitem>
<para>Runs <literal>sgml-tag-region</literal>. Select some text (move
to start of text, C-space, move to end of text, C-space) and then
run this command. You will be prompted for the element to use. This
element will then be inserted immediately before and after your
marked region.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>C-c -</command></term>
<listitem>
<para>Runs <literal>sgml-untag-element</literal>. Place the point
within the start or end tag of an element you want to remove, and
run this command. The element's start and end tags will be
removed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>C-c C-q</command></term>
<listitem>
<para>Runs <literal>sgml-fill-element</literal>. Will recursively fill
(i.e., reformat) content from the current element in. The filling
<emphasis>will</emphasis> affect content in which whitespace is
significant, such as within <sgmltag>programlisting</sgmltag>
elements, so run this command with care.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>C-c C-a</command></term>
<listitem>
<para>Runs <literal>sgml-edit-attributes</literal>. Opens a second
buffer containing a list of all the attributes for the closest
enclosing element, and their current values. Use TAB to navigate
between attributes, <command>C-k</command> to remove an existing
value and replace it with a new one, <command>C-c</command> to close
this buffer and return to the main document.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>C-c C-v</command></term>
<listitem>
<para>Runs <literal>sgml-validate</literal>. Prompts you to save the
current document (if necessary) and then runs an SGML validator. The
output from the validator is captured into a new buffer, and you can
then navigate from one troublespot to the next, fixing markup errors
as you go.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Doubtless there are other useful functions of this mode, but those are
the ones I use most often.</para>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../book.sgml" "part" "chapter")
End:
-->

121
en/tutorials/docproj-primer/see-also/chapter.sgml
View file

@ -1,121 +0,0 @@
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
$Id: chapter.sgml,v 1.2 1999-07-14 19:27:14 nik Exp $
-->
<chapter id="see-also">
<title>See Also</title>
<para>This document is deliberately not an exhaustive discussion of SGML,
the DTDs listed, and the FreeBSD Documentation Project. For more
information about these, you are encouraged to see the following web
sites.</para>
<sect1>
<title>The FreeBSD Documentation Project</title>
<itemizedlist>
<listitem>
<para><ulink url="http://www.freebsd.org/docproj/">The FreeBSD
Documentation Project web pages</ulink></para>
</listitem>
<listitem>
<para><ulink url="http://www.freebsd.org/handbook/">The FreeBSD Handbook</ulink></para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>SGML</title>
<itemizedlist>
<listitem>
<para><ulink url="http://www.oasis-open.org/cover/">The SGML/XML web
page</ulink>, a comprehensive SGML resource</para>
</listitem>
<listitem>
<para><ulink
url='http://etext.virginia.edu/bin/tei-tocs?div=DIV1&amp;id=SG">http://etext.virginia.edu/bin/tei-tocs?div=DIV1&amp;id=SG'>Gentle introduction to SGML</ulink></para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>HTML</title>
<itemizedlist>
<listitem>
<para><ulink url="http://www.w3.org/">The World Wide Web
organisation</ulink></para>
</listitem>
<listitem>
<para><ulink url="http://www.w3.org/TR/REC-html40/">The HTML 4.0
specification</ulink></para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>DocBook</title>
<itemizedlist>
<listitem>
<para><ulink url="http://www.oreilly.com/davenport/">The Davenport
Group</ulink>, maintainers of the DocBook DTD</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>The Linux Documentation Project</title>
<itemizedlist>
<listitem>
<para><ulink url="http://metalab.unc.edu/LDP/">The Linux Documentation
Project web pages</ulink></para>
</listitem>
</itemizedlist>
</sect1>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../book.sgml" "part" "chapter")
End:
-->

2213
en/tutorials/docproj-primer/sgml-markup/chapter.sgml
View file

File diff suppressed because it is too large Load diff

1589
en/tutorials/docproj-primer/sgml-primer/chapter.sgml
View file

File diff suppressed because it is too large Load diff

70
en/tutorials/docproj-primer/stylesheets/chapter.sgml
View file

@ -1,70 +0,0 @@
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
$Id: chapter.sgml,v 1.2 1999-07-14 19:22:45 nik Exp $
-->
<chapter id="stylesheets">
<title>* Stylesheets</title>
<para>SGML says nothing about how a document should be displayed to the
user, or rendered on paper. To do that, various languages have been
developed to describe stylesheets, including DynaText, Panorama, SPICE,
JSSS, FOSI, CSS, and DSSSL.</para>
<para>For DocBook, we are using stylesheets written in DSSSL. For HTML we
are using CSS.</para>
<sect1>
<title>* DSSSL</title>
<para>The Documentation Project uses a slightly customised version of
Norm Walsh's modular DocBook stylesheets.</para>
<para>These can be found in
<filename>textproc/dsssl-docbook-modular</filename>.</para>
</sect1>
<sect1>
<title>* CSS</title>
<para></para>
</sect1>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../book.sgml" "part" "chapter")
End:
-->

49
en/tutorials/docproj-primer/the-faq/chapter.sgml
View file

@ -1,49 +0,0 @@
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
$Id: chapter.sgml,v 1.2 1999-07-14 19:20:30 nik Exp $
-->
<chapter id="the-faq">
<title>* The FAQ</title>
<para></para>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../book.sgml" "part" "chapter")
End:
-->

282
en/tutorials/docproj-primer/the-handbook/chapter.sgml
View file

@ -1,282 +0,0 @@
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
$Id: chapter.sgml,v 1.5 1999-07-30 20:51:00 nik Exp $
-->
<chapter id="the-handbook">
<title>* The Handbook</title>
<sect1>
<title>Logical structure</title>
<para>The Handbook is written to comply with the FreeBSD DocBook extended
DTD.</para>
<para>The Handbook is organised as a DocBook <sgmltag>book</sgmltag>. It
is then divided into <sgmltag>part</sgmltag>s, each of which may contain
several <sgmltag>chapter</sgmltag>s. <sgmltag>chapter</sgmltag>s are
further subdivided into sections (<sgmltag>sect1</sgmltag>) and
subsections (<sgmltag>sect2</sgmltag>, <sgmltag>sect3</sgmltag>) and so
on.</para>
</sect1>
<sect1>
<title>Physical organisation</title>
<para>The Handbook (and its translations) are in the
<filename>doc/<replaceable>language</replaceable>/handbook</filename>
subdirectory of the main CVS
repository. <replaceable>language</replaceable> corresponds to the ISO
language code for that translation, <literal>en</literal> for English,
<literal>ja</literal> for Japanese, and so on.</para>
<para>There are a number of files and directories within the
<filename>handbook</filename> directory.</para>
<note>
<para>The Handbook's organisation may change over time, and this
document may lag in detailing the organisational changes. If you have
any questions about how the Handbook is organised, please contact the
FreeBSD Documentation Project, <email>doc@FreeBSD.ORG</email>.</para>
</note>
<sect2>
<title><filename>Makefile</filename></title>
<para>The <filename>Makefile</filename> defines the rules that are used
to convert the Handbook from its source form (DocBook) to a number of
other target formats (including HTML, PostScript, and plain
text).</para>
<para>A more detailed description of the <filename>Makefile</filename>
is in <xref linkend="the-handbook-converting">.</para>
</sect2>
<sect2>
<title><filename>handbook.sgml</filename></title>
<para>This is the top level document in the Handbook. It contains the
Handbook's <link linkend="sgml-primer-doctype-declaration">DOCTYPE
declaration</link>, as well as the elements that describe the
Handbook's structure.</para>
<para><filename>handbook.sgml</filename> uses <link
linkend="sgml-primer-parameter-entities">parameter entities</link>
to load in the files with the <filename>.ent</filename> extension.
These files (described later) then define <link
linkend="sgml-primer-general-entities">general entities</link> that
are used throughout the rest of the Handbook.</para>
</sect2>
<sect2>
<title><filename><replaceable>directory</replaceable>/chapter.sgml</filename></title>
<para>Each chapter in the Handbook is stored in a file called
<filename>chapter.sgml</filename> in a separate directory from the
other chapters. Each directory is named after the value of the
<literal>id</literal> attribute on the <sgmltag>chapter</sgmltag>
element.</para>
<para>For example, if one of the chapter files contains:</para>
<programlisting><![ CDATA [
<chapter id="kernelconfiguration">
...
</chapter>]]></programlisting>
<para>then it will be called <filename>chapter.sgml</filename> in the
<filename>kernelconfiguration</filename> directory. In general, the
entire contents of the chapter will be held in this file.</para>
<para>When the HTML version of the Handbook is produced, this will yield
<filename>kernelconfiguration.html</filename>. This is because of the
<literal>id</literal> value, and is not related to the name of the
directory.</para>
<para>In earlier versions of the Handbook the files were stored in the
same directory as <filename>handbook.sgml</filename>, and named after
the value of the <literal>id</literal> attribute on the file's
<sgmltag>chapter</sgmltag> element. Moving them in to separate
directories prepares for future plans for the Handbook. Specifically,
it will soon be possible to include images in each chapter. It
makes more sense for each image to be stored in a directory with the
text for the chapter than to try and keep the text for all the
chapters, and all the images, in one large directory. Namespace
collisions would be inevitable, and it is easier to work with several
directories with a few files in them than it is to work with one
directory that has many files in it.</para>
<para>A brief look will show that there are many directories with
individual <filename>chapter.sgml</filename> files, including
<filename>basics/chapter.sgml</filename>,
<filename>introduction/chapter.sgml</filename>, and
<filename>printing/chapter.sgml</filename>.</para>
<important>
<para>Chapters and/or directories should not be named in a fashion
that reflects their ordering within the Handbook. This ordering
might change as the content within the Handbook is reorganised; this
sort of reorganistion should not (generally) include the need to
rename files (unless entire chapters are being promoted or demoted
within the hierarchy).</para>
</important>
<para>Each <filename>chapter.sgml</filename> file will not be a complete
SGML document. In particular, they will not have their own DOCTYPE
line at the start of the file.</para>
<para>This is unfortunate for two reasons;</para>
<itemizedlist>
<listitem>
<para>It makes it impossible to treat these as generic SGML files
and simply convert them to HTML, RTF, PS, and other formats in the
same way the main Handbook is generated. This
<emphasis>would</emphasis> force you to rebuild the Handbook every
time you want to see the effect a change as had on just one
chapter.</para>
</listitem>
<listitem>
<para>Emacs' <literal>sgml-mode</literal> can not use it to
determine the DTD to use, losing useful benefits of
<literal>sgml-mode</literal> (element completion, automatic
validation, and so on).</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<sect1>
<title>Style guide</title>
<para>To keep the source for the Handbook consistent when many different
people are editing it, please follow these style conventions.</para>
<sect2>
<title>Letter case</title>
<para>Tags are entered in lower case, <literal>&lt;para&gt;</literal>,
<emphasis>not</emphasis> <literal>&lt;PARA&gt;</literal>.</para>
<para>Text that appears in SGML contexts is generally written in upper
case, <literal>&lt!ENTITY&hellip;&gt;</literal>, and
<literal>&lt;!DOCTYPE&hellip;&gt;</literal>, <emphasis>not</emphasis>
<literal>&lt;!entity&hellip;&gt;</literal> and
<literal>&lt;!doctype&hellip;&gt;</literal>.</para>
</sect2>
<sect2>
<title>Indentation</title>
<para>Each file starts with indentation set at column 0,
<emphasis>regardless</emphasis> of the indentation level of the file
which might contain this one.</para>
<para>Every start tag increases the indentation level by 2 spaces, and
every end tag decreases the indentation level by 2 spaces. Content
within elements should be indented by two spaces if the content runs
over more than one line.</para>
<para>For example, the source for this section looks something
like;</para>
<programlisting>
<![ CDATA [+--- This is column 0
V
<chapter>
<title>...</title>
<sect1>
<title>...</title>
<sect2>
<title>Indentation</title>
<para>Each file starts with indentation set at column 0,
<emphasis>regardless</emphasis> of the indentation level of the file
which might contain this one.</para>
<para>Every start tag increases the indentation level by 2 spaces, and
every end tag decreases the indentation level by 2 spaces. Content
within elements should be indented by two spaces if the content runs
over more than one line.</para>
...
</sect2>
</sect1>
</chapter>]]></programlisting>
<para>If you use <application>Emacs</application> or
<application>Xemacs</application> to edit the files then
<literal>sgml-mode</literal> should be loaded automatically, and the
Emacs local variables at the bottom of each file should enforce these
styles.</para>
</sect2>
<sect2>
<title>White space changes</title>
<para>When committing changes, <emphasis>do not commit changes to the
content at the same time as changes to the
formatting</emphasis>.</para>
<para>This is so that the teams that convert the Handbook to other
languages can quickly see what content has actually changed in your
commit, without having to decide whether a line has changed because of
the content, or just because it has been refilled.</para>
<para>For example, if you have added two sentances to a paragraph, such
that the line lengths on the paragraph now go over 80 columns, first
commit your change with the too-long line lengths. Then fix the line
wrapping, and commit this second change. In the commit message for
the second change, be sure to indicate that this is a whitespace-only
change, and that the translation team can ignore it.</para>
</sect2>
</sect1>
<sect1 id="the-handbook-converting">
<title>Converting the Handbook to other formats</title>
<para></para>
</sect1>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../book.sgml" "part" "chapter")
End:
-->

49
en/tutorials/docproj-primer/the-website/chapter.sgml
View file

@ -1,49 +0,0 @@
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
$Id: chapter.sgml,v 1.2 1999-07-14 19:22:46 nik Exp $
-->
<chapter id="the-website">
<title>* The Website</title>
<para></para>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../book.sgml" "part" "chapter")
End:
-->

284
en/tutorials/docproj-primer/tools/chapter.sgml
View file

@ -1,284 +0,0 @@
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML, HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
$Id: chapter.sgml,v 1.4 1999-07-14 19:19:24 nik Exp $
-->
<chapter id="tools">
<title>Tools</title>
<para>The FDP uses a number of different software tools to help
manage the FreeBSD documentation, convert it to different output
formats, and so on. You will need to use these tools yourself if
you are to work with the FreeBSD documentation.</para>
<para>All these tools are available as FreeBSD Ports and Packages,
greatly simplifying the work you have to do to install
them.</para>
<para>You will need to install these tools before you work through
any of the examples in later chapters. The actual usage of these
tools is covered in these later chapters.</para>
<important>
<title>Use <filename>textproc/docproj</filename> if possible</title>
<para>You can save yourself a lot of time if you install the
<filename>textproc/docproj</filename> port. This is a
<emphasis>meta-port</emphasis> which does not contain any software
itself. Instead, it depends on various other ports being installed
correctly. Installing this port <emphasis>should</emphasis>
automatically download and install all of the packages listed in this
chapter that you need that are missing from your system.</para>
<para>One of the packages that you might need is the JadeTeX macro set.
In turn, this macro set requires that TeX is installed. TeX is a large
package, and you only need it if you want to produce Postscript or PDF
output.</para>
<para>To save yourself time and space you must specify whether or not you
want JadeTeX (and therefore TeX) installed when you install this port.
Either do;
<screen>&prompt.root; <userinput>make JADETEX=yes install</userinput></screen>
or
<screen>&prompt.root; <userinput>make JADETEX=no install</userinput></screen>
as necessary.</para>
</important>
<sect1>
<title>Mandatory tools</title>
<sect2>
<title>Software</title>
<para>These programs are required before you can usefully work with
the FreeBSD documentation. They are all included in
<filename>textproc/docproj</filename>.</para>
<variablelist>
<varlistentry>
<term><application>SP</application>
(<filename>textproc/sp</filename>)</term>
<listitem>
<para>A suite of applications, including a validating SGML parser,
and an SGML normaliser.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><application>Jade</application>
(<filename>textproc/jade</filename>)</term>
<listitem>
<para>A DSSSL implementation. Used for converting marked up
documents to other formats, including HTML and TeX.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><application>Tidy</application>
(<filename>www/tidy</filename>)</term>
<listitem>
<para>An HTML 'pretty printer', used to reformat some of the
automatically generated HTML so that it is easier to
follow.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><application>Lynx</application>
(<filename>www/lynx-current</filename>)</term>
<listitem>
<para>A text-mode WWW browser, &man.lynx.1; can also convert
HTML files to plain text.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2>
<title>DTDs and Entities</title>
<para>These are the DTDs and entity sets used by the FDP. They need to
be installed before you can work with any of the documentation.</para>
<variablelist>
<varlistentry>
<term>HTML DTD (<filename>textproc/html</filename>)</term>
<listitem>
<para>HTML is the markup language of choice for the World Wide
Web, and is used throughout the FreeBSD web site.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LinuxDoc DTD (<filename>textproc/linuxdoc</filename>)</term>
<listitem>
<para>Some FreeBSD documentation is marked up in LinuxDoc. The
FDP is actively migrating from LinuxDoc to DocBook.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DocBook DTD (<filename>textproc/docbook</filename>)</term>
<listitem>
<para>DocBook is designed for marking up technical documentation,
and the FDP is migrating from LinuxDoc to DocBook. At the time
of writing, this document, and the FreeBSD Handbook are marked
up in DocBook.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ISO 8879 entities
(<filename>textproc/iso8879</filename>)</term>
<listitem>
<para>19 of the ISO 8879:1986 character entity sets used by many
DTDs. Includes named mathematical symbols, additional
characters in the 'latin' character set (accents, diacriticals,
and so on), and greek symbols.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2>
<title>Stylesheets</title>
<para>The stylesheets are used when converting and formatting the
documentation for display on screen, printing, and so on.</para>
<variablelist>
<varlistentry>
<term>Modular DocBook Stylesheets
(<filename>textproc/dsssl-docbook-modular</filename>)</term>
<listitem>
<para>The Modular DocBook Stylesheets are used when converting
documentation marked up in DocBook to other formats, such as
HTML, or RTF.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>
<sect1>
<title>Optional tools</title>
<para>You do not need to have any of the following installed. However,
you may find it easier to work with the documentation if you do, and
they may give you more flexibility in the output formats that can be
generated.</para>
<sect2>
<title>Software</title>
<variablelist>
<varlistentry>
<term><application>JadeTeX</application> and
<application>teTeX</application>
(<filename>print/jadetex</filename> and
<filename>print/teTeX-beta</filename>)</term>
<listitem>
<para><application>Jade</application> and
<application>teTeX</application> are used to convert DocBook
documents to DVI, Postscript, and PDF formats. The
<application>JadeTeX</application> macros are needed in order to
do this.</para>
<para>If you do not intend to convert your documentation to one of
these formats (i.e., HTML, plain text, and RTF are sufficient)
then you do not need to install
<application>JadeTeX</application> and
<application>teTeX</application>. This can be a significant
space and time saver, as <application>teTeX</application> is
over 30MB in size.</para>
<important>
<para>If you decide to install
<application>JadeTeX</application> and
<application>teTeX</application> then you will need to
configure <application>teTeX</application> after
<application>JadeTeX</application> has been installed.
<filename>print/jadetex/pkg/MESSAGE</filename> contains
detailed instructions explaining what you need to do.</para>
</important>
</listitem>
</varlistentry>
<varlistentry>
<term><application>Emacs</application> or
<application>xemacs</application>
(<filename>editors/emacs</filename> or
<filename>editors/xemacs</filename>)</term>
<listitem>
<para>Both these editors include a special mode for editing
documents marked up according to an SGML DTD. This mode
includes commands to reduce the amount of typing you need, and
help reduce the possibility of errors.</para>
<para>You do not need to use them, any text editor can be used to
edit marked up documents. You may find they make you
efficient.</para>
</listitem>
</varlistentry>
</variablelist>
<para>If anyone has recommendations for other software that is useful
when manipulating SGML documents, please let Nik Clayton
(<email>nik@freebsd.org</email>) know, so they can be added to this
list.</para>
</sect2>
</sect1>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../book.sgml" "part" "chapter")
End:
-->

474
en/tutorials/docproj-primer/translations/chapter.sgml
View file

@ -1,474 +0,0 @@
<!-- Copyright (c) 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
$Id: chapter.sgml,v 1.1 1999-07-14 22:30:26 nik Exp $
-->
<chapter id="translations">
<title>Translations</title>
<para>This is the FAQ for people translating the FreeBSD documentation
(FAQ, Handbook, tutorials, man pages, and others) to different
languages.</para>
<para>It is <emphasis>very</emphasis> heavily based on the translation FAQ
from the FreeBSD German Documentation Project, originally written by Frank
Grnder <email>elwood@mc5sys.in-berlin.de</email> and translated back to
English by Bernd Warken <email>bwarken@mayn.de</email>.</para>
<para>The FAQ maintainer is Nik Clayton
<email>nik@FreeBSD.org</email>.</para>
<qandaset>
<qandaentry>
<question>
<para>Why a FAQ?</para>
</question>
<answer>
<para>More and more people are approaching the freebsd-doc mailing
list and volunteering to translate FreeBSD documentation to other
languages. This FAQ aims to answer their questions so they can start
translating documentation as quickly as possible.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>What do <phrase>i18n</phrase> and <phrase>l10n</phrase>
mean?</para>
</question>
<answer>
<para><phrase>i18n</phrase> means
<phrase>internationalisation</phrase> and <phrase>l10n</phrase>
means <phrase>localisation</phrase>. They are just a convenient
shorthand.</para>
<para><phrase>i18n</phrase> can be read as &ldquo;i&rdquo; followed by
18 letters, followed by &ldquo;n&rdquo;. Similarly,
<phrase>l10n</phrase> is &ldquo;l&rdquo; followed by 10 letters,
followed by &ldquo;n&rdquo;.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Is there a mailing list for translators?</para>
</question>
<answer>
<para>Yes, <email>freebsd-translate@ngo.org.uk</email>. Subscribe by
sending a message to
<email>freebsd-translate-request@ngo.org.uk</email> with the word
<literal>subscribe</literal> in the body of the message.</para>
<para>You will receive a reply asking you to confirm your subscription
(in exactly the same manner as the the FreeBSD lists at <hostid
role="domainname">FreeBSD.org</hostid>).</para>
<para>The primary language of the mailing list is English. However,
posts in other languages will be accepted. The mailing list is not
moderated, but you need to be a member of the list before you can
post to it.</para>
<para>The mailing list is archived, but they are not currently
searchable. Sending the message <literal>help</literal> to
<email>majordomo@ngo.org.uk</email> will send back instructions on
how to access the archive.</para>
<para>It is expected that the mailing list will transfer to <hostid
role="domainname">FreeBSD.org</hostid> and therefore become
<emphasis>official</emphasis> in the near future.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Are more translators needed?</para>
</question>
<answer>
<para>Yes. The more people work on translation the faster it gets
done, and the faster changes to the English documentation are
mirrored in the translated documents.</para>
<para>You do not have to be a professional translator to be able to
help.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>What languages do I need to know?</para>
</question>
<answer>
<para>Ideally, you will have a good knowledge of written English, and
obviously you will need to be fluent in the language you are
translating to.</para>
<para>English is not strictly necessary. For example, you could do a
Hungarian translation of the FAQ from the Spanish
translation.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>What software do I need to know?</para>
</question>
<answer>
<para>It is strongly recommended that you maintain a local copy of the
FreeBSD CVS repository (at least the documentation part) either
using <application>CTM</application> or
<application>CVSup</application>. The "Staying current with FreeBSD"
chapter in the Handbook explains how to use these
applications.</para>
<para>You should be comfortable using <application>CVS</application>.
This will allow you to see what has changed between different
versions of the files that make up the documentation.</para>
<para>[XXX To Do -- write a tutorial that shows how to use CVSup to
get just the documentation, check it out, and see what's changed
between two arbitrary revisions]</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>How do I find out who else might be translating to the same
language?</para>
</question>
<answer>
<para>The <ulink
url="http://www.freebsd.org/docproj/translations.html">Documentation
Project translations page</ulink> lists the translation efforts
that are currently known about. If someone else is already working
on translating documentation to your language, please don't
duplicate their efforts. Instead, contact them to see how you can
help.</para>
<para>If no one is listed on that page as translating for your
language then send a message to
<email>freebsd-doc@freebsd.org</email> in case someone else is
thinking of doing a translation, but hasn't announced it yet.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>No one else is translating to my language. What do I do?</para>
</question>
<answer>
<para>Congratulations, you have just started the &ldquo;FreeBSD
<replaceable>your-language-here</replaceable> Documentation
Translation Project&rdquo;. Welcome aboard.</para>
<para>First, decide whether or not you've got the time to spare. Since
you are the only person working on your language at the moment it is
going to be your responsibility to publicise your work and
coordinate any volunteers that might want to help you.</para>
<para>Write an e-mail to the Documentation Project mailing list,
announcing that you are going to translate the documentation, so the
Documentation Project translations page can be maintained.</para>
<para>You should subscribe to the
<email>freebsd-translate@ngo.org.uk</email> mailing list (as
described earlier).</para>
<para>If there is already someone in your country providing FreeBSD
mirroring services you should contact them and ask if they can
provide some webspace for your project, and possibly an e-mail
address or mailing list services.</para>
<para>Then pick a document and start translating. It is best to start
with something fairly small&mdash;either the FAQ, or one of the
tutorials.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>I've translated some documentation, where do I send it?</para>
</question>
<answer>
<para>That depends. If you are already working with a translation team
(such as the Japanese team, or the German team) then they will have
their own procedures for handling submitted documentation, and these
will be outlined on their web pages.</para>
<para>If you are the only person working on a particular language (or
you are responsible for a translation project and want to submit
your changes back to the FreeBSD project) then you should send your
translation to the FreeBSD project (see the next question).</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>I'm the only person working on translating to this language, how
do I submit my translation?</para>
<para>or</para>
<para>We're a translation team, and want to submit documentation that
our members have translated for us?</para>
</question>
<answer>
<para>First, make sure your translation is organised properly. This
means that it should drop in to the existing documentation tree and
build straight away.</para>
<para>Currently, the FreeBSD documentation is stored in a top level
directory called <filename>doc/</filename>. Directories below this
are named according to the language code they are written in, as
defined in ISO639 (<filename>/usr/share/misc/iso639</filename> on a
version of FreeBSD newer than 20th January 1999).</para>
<para>If your language can be encoded in different ways (for example,
Chinese) then there should be directories below this, one for each
encoding format you have provided.</para>
<para>Finally, you should have directories for each document.</para>
<para>For example, a hypothetical Swedish translation might look
like</para>
<programlisting> doc/
sv/
Makefile
FAQ/
Makefile
*.sgml</programlisting>
<para><literal>sv</literal> is the ISO639 code for Swedish. Note the
two Makefiles, which will be used to build the documentation. There
is no separate language code for Swedish, so there is no
intermittent directory between the "sv" and "FAQ"
directories<footnote>
<para>This directory structure is going to change radically quite
soon. Please see the on-going discussions on the
<email>doc@FreeBSD.org</email> mailing list for more
information.</para>
</footnote>.</para>
<para>Use &man.tar.1; and &man.gzip.1; to compress up your
documentation, and send it to the project.</para>
<screen>&prompt.user; <userinput>cd doc</userinput>
&prompt.user; <userinput>tar cf swedish-docs.tar sv</userinput>
&prompt.user; <userinput>gzip -9 swedish-docs.tar</userinput></screen>
<para>Put <filename>swedish-docs.tar.gz</filename> somewhere. If you
do not have access to your own webspace (perhaps your ISP does not
let you have any) then you can e-mail Nik Clayton
<email>nik@FreeBSD.org</email>, and arrange to e-mail the files
when it is convenient.</para>
<para>Either way, you should use &man.send-pr.1; to submit a report
indicating that you have submitted the documentation. It would be
very helpful if you could get other people to look over your
translation and double check it first, since it is unlikely that the
person committing it will be fluent in the language.</para>
<para>Someone (probably the Documentation Project Manager, currently
Nik Clayton <email>nik@FreeBSD.org</email>) will then take your
translation and confirm that it builds. In particular, the
following things will be looked at:</para>
<orderedlist>
<listitem>
<para>Do all your files use RCS strings (such as "ID").</para>
</listitem>
<listitem>
<para>Does <command>make all</command> in the
<filename>sv</filename> directory work correctly.</para>
</listitem>
<listitem>
<para>Does <command>make install</command> work correctly.</para>
</listitem>
</orderedlist>
<para>If there are any problems then whoever is looking at the
submission will get back to you to try and work them out.</para>
<para>If there are no problems then your translation will be committed
as soon as possible.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Can I include language or country specific text in my
translation?</para>
</question>
<answer>
<para>We would prefer that you did not.</para>
<para>For example, suppose that you are translating the Handbook to
Korean, and want to include a section about retailers in Korea in
your Handbook.</para>
<para>There's no real reason why that information should not be in the
English (or German, or Spanish, or Japanese, or &hellip;) versions
as well. It is feasible that an English speaker in Korea might try
and pick up a copy of FreeBSD whilst over there. It also helps
increase FreeBSD's perceived presence around the globe, which is not
a bad thing.</para>
<para>If you have country specific information, please submit it as a
change to the English Handbook (using &man.send-pr.1;) and then
translate the change back to your language in the translated
Handbook.</para>
<para>Thanks.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>How should language specific characters be included?</para>
<para>Non-ASCII characters in the documentation should be included
using SGML entities.</para>
<para>Briefly, these look like an ampersand (&amp;), the name of the
entity, and a semi-colon (;).</para>
<para>The entity names are defined in ISO8879, which is in the ports
tree as <filename>textproc/iso8879</filename>.</para>
<para>A few examples include</para>
<segmentedlist>
<seglistitem>
<seg>&amp;eacute;</seg>
<seg>&eacute;</seg>
<seg>Small &ldquo;e&rdquo; with an acute accent</seg>
</seglistitem>
<seglistitem>
<seg>&amp;Eacute;</seg>
<seg>&Eacute;</seg>
<seg>Large &ldquo;E&rdquo; with an acute accent</seg>
</seglistitem>
<seglistitem>
<seg>&amp;uuml;</seg>
<seg>&uuml;</seg>
<seg>Small &ldquo;u&rdquo; with an umlaut</seg>
</seglistitem>
</segmentedlist>
<para>After you have installed the iso8879 port, the files in
<filename>/usr/local/share/sgml/iso8879</filename> contain the
complete list.</para>
</question>
</qandaentry>
<qandaentry>
<question>
<para>Addressing the reader</para>
</question>
<answer>
<para>In the English documents, the reader is addressed as
&ldquo;you&rdquo;, there is no formal/informal distinction as there
is in some languages.</para>
<para>If you are translating to a language which does distinguish, use
whichever form is typically used in other technical documentation in
your language. If in doubt, use a mildly polite form.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Do I need to include any additional information in my
translations?</para>
</question>
<answer>
<para>Yes.</para>
<para>The header of the English version of each document will look
something like this;</para>
<programlisting><![ CDATA [<!--
The FreeBSD Documentation Project
&dollar;Id: chapter.sgml,v 1.11 1999/06/20 21:18:57 billf Exp $
-->]]></programlisting>
<para>The exact boilerplate may change, but it will always include an
Id line and the phrase <literal>The FreeBSD Documentation
Project</literal>.</para>
<para>Your translated documents should include their own Id line, and change the
<literal>FreeBSD Documentation Project</literal> line to
<literal>The FreeBSD <replaceable>language</replaceable>
Documentation Project</literal>.</para>
<para>In addition, you should add a third line which indicates which
revision of the English text this is based on.</para>
<para>So, the Spanish version of this file might start</para>
<programlisting><![ CDATA [<!--
The FreeBSD Spanish Documentation Project
&dollar;Id: chapter.sgml,v 1.3 1999/06/24 19:12:32 jesusr Exp $
Original revision: 1.11
-->]]></programlisting>
</answer>
</qandaentry>
</qandaset>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../book.sgml" "part" "chapter")
End:
-->

143
en/tutorials/docproj-primer/writing-style/chapter.sgml
View file

@ -1,143 +0,0 @@
<!-- Copyright (c) 1998 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
$Id: chapter.sgml,v 1.3 1999-07-30 21:09:07 nik Exp $
-->
<chapter id="writing-style">
<title>Writing style</title>
<para>In order to promote consistency between the myriad authors of the
FreeBSD documentation, some guidelines have been drawn up for authors to
follow.</para>
<variablelist>
<varlistentry>
<term>Do not use contractions</term>
<listitem>
<para>Do not use contractions. Always spell the phrase out in full.
&ldquo;Don't use contractions&rdquo; would be wrong.</para>
<para>Avoiding contractions makes for a more formal tone, is more
precise, and slightly easier for translators.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Use the serial comma</term>
<listitem>
<para>In a list of items within a paragraph, seperate each item from
the others with a comma. Seperate the last item from the others with
a comma and the word &ldquo;and&rdquo;.</para>
<para>For example, look at the following quote;</para>
<blockquote>
<para>This is a list of one, two and three items.</para>
</blockquote>
<para>Is this a list of three items, &ldquo;one&rdquo;,
&ldquo;two&rdquo;, and &ldquo;three&rdquo;, or a list of two items,
&ldquo;one&rdquo; and &ldquo;two and three&rdquo;?</para>
<para>It is better to be explicit and include a serial comma;</para>
<blockquote>
<para>This is a list of one, two, and three items.</para>
</blockquote>
</listitem>
</varlistentry>
<varlistentry>
<term>Avoid redundant phrases</term>
<listitem>
<para>Try not to use redundant phrases. In particular, &ldquo;the
command&rdquo;, &ldquo;the file&rdquo;, and &ldquo;man
command&rdquo; are probably redundant.</para>
<para>These two examples show this for commands. The second example
is preferred.</para>
<informalexample>
<para>Use the command <command>cvsup</command> to update your
sources</para>
</informalexample>
<informalexample>
<para>Use <command>cvsup</command> to update your sources</para>
</informalexample>
<para>These two examples show this for filenames. The second example
is preferred.</para>
<informalexample>
<para>&hellip; in the filename
<filename>/etc/rc.local</filename>&hellip;</para>
</informalexample>
<informalexample>
<para>&hellip; in
<filename>/etc/rc.local</filename>&hellip;</para>
</informalexample>
<para>These two examples show this for manual references. The second
example is preferred (the second example uses
<sgmltag>citerefentry</sgmltag>).</para>
<informalexample>
<para>See <command>man csh</command> for more
information.</para>
</informalexample>
<informalexample>
<para>See &man.csh.1;</para>
</informalexample>
</listitem>
</varlistentry>
</variablelist>
<para>For more information about writing style, see <ulink
url="http://www.columbia.edu/acis/bartleby/strunk/">Elements of
Style</ulink>, by William Strunk.</para>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../book.sgml" "part" "chapter")
End:
-->

6
en/tutorials/fonts/Makefile
View file

@ -1,6 +0,0 @@
# $Id: Makefile,v 1.4 1997-07-01 05:38:13 max Exp $
DOCS= fonts.docb
INDEXLINK= fonts.html
.include "../../web.mk"

951
en/tutorials/fonts/fonts.docb
View file

@ -1,951 +0,0 @@
<!-- $Id: fonts.docb,v 1.3 1999-08-06 17:35:18 nik Exp $ -->
<!-- The FreeBSD Documentation Project -->
<!DOCTYPE BOOK PUBLIC "-//Davenport//DTD DocBook V3.0//EN">
<!-- Recently, I wanted to figure out how to use some additional fonts that
I had accumulated. I finally figured out *how to do it* from the various
man pages and documentation. Since it might be of use to other users,
and I didn't see any reference to this topic in the FAQ or handbook, I
thought I'd try my hand at a simple cookbook tutorial addressing the
use of fonts. I have included my unanswered questions at the end of
the document.
Anyway, here's what I put together. This is my present understanding of
fonts and how to use them with FreeBSD. I am sure that there are errors or
misunderstandings, but it contains enough valid information to allow the
use of additional fonts with Ghostscript, X11 and Groff. This is my first
attempt to write anything along the lines of a tutorial/FAQ, so I am sure
it is pretty raw. There are probably better ways to do some of this stuff,
and I would welcome being corrected.
-->
<book>
<bookinfo>
<bookbiblio>
<title>Fonts and FreeBSD</title>
<subtitle>A Tutorial</subtitle>
<authorgroup>
<author>
<firstname>Dave</firstname>
<surname>Bodenstab</surname>
<affiliation>
<address><email>imdave@synet.net</email></address>
</affiliation>
</author>
</authorgroup>
<pubdate>Wed Aug 7, 1996</pubdate>
<abstract><para>This document contains a description of the various
font files that may be used with FreeBSD and the syscons driver, X11,
Ghostscript and Groff. Cookbook examples are provided for switching
the syscons display to 80x60 mode, and for using type 1 fonts with
the above application programs.</para></abstract>
</bookbiblio>
</bookinfo>
<chapter>
<title>Introduction</title>
<para>There are many sources of fonts available, and one might ask
how they might be used with FreeBSD. The answer can be found by
carefully searching the documentation for the component that one
would like to use. This is very time consuming, so this tutorial is
an attempt to provide a shortcut for others who might be
interested.</para>
</chapter>
<chapter>
<title>Basic terminology</title>
<para>There are many different font formats and associated font file
suffixes. A few that will be addressed here are:
<variablelist>
<varlistentry><term><filename>.pfa</>, <filename>.pfb</></term>
<listitem><para>Postscript type 1 fonts. The <filename>.pfa</filename> is the
<emphasis>A</emphasis>scii form and <filename>.pfb</filename> the
<emphasis>B</emphasis>inary form.</para></listitem>
</varlistentry>
<varlistentry><term><filename>.afm</></term>
<listitem><para>The font metrics associated with a type 1
font.</para></listitem>
</varlistentry>
<varlistentry><term><filename>.pfm</></term>
<listitem><para>The printer font metrics associated with a type 1
font.</para></listitem>
</varlistentry>
<varlistentry><term><filename>.ttf</></term>
<listitem><para>A TrueType font</para></listitem>
</varlistentry>
<varlistentry><term><filename>.fot</></term>
<listitem><para>An indirect reference to a TrueType font (not an
actual font)</para></listitem>
</varlistentry>
<varlistentry><term><filename>.fon</>, <filename>.fnt</></term>
<listitem><para>Bitmapped screen fonts</para></listitem>
</varlistentry>
</variablelist></para>
<para>The <filename>.fot</filename> file is used by Windows as sort
of a symbolic link to the actual TrueType font
(<filename>.ttf</filename>) file. The <filename>.fon</filename> font
files are also used by Windows. I know of no way to use this font
format with FreeBSD.</para>
</chapter>
<chapter>
<title>What font formats can I use?</title>
<para>Which font file format is useful depends on the application
being used. FreeBSD by itself uses no fonts. Application programs
and/or drivers may make use of the font files. Here is a small cross
reference of application/driver to the font type suffixes:</para>
<para>
<variablelist>
<varlistentry><term>Driver</term>
<listitem>
<para>
<variablelist>
<varlistentry><term>syscons</term>
<listitem>
<para><filename>.fnt</></para>
</listitem>
</varlistentry>
</variablelist>
</para>
</listitem>
</varlistentry>
<varlistentry><term>Application</term>
<listitem>
<para>
<variablelist>
<varlistentry><term>Ghostscript</term>
<listitem>
<para><filename>.pfa</filename>, <filename>.pfb</filename>, <filename>.ttf</filename></para>
</listitem>
</varlistentry>
<varlistentry><term>X11</term>
<listitem>
<para><filename>.pfa</filename>, <filename>.pfb</filename></para>
</listitem>
</varlistentry>
<varlistentry><term>Groff</term>
<listitem>
<para><filename>.pfa</filename>, <filename>.afm</filename></para>
</listitem>
</varlistentry>
<varlistentry><term>Povray</term>
<listitem>
<para><filename>.ttf</filename></para>
</listitem>
</varlistentry>
</variablelist>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>The <filename>.fnt</filename> suffix is used quite frequently.
I suspect that whenever someone wanted to create a specialized font
file for their application, more often than not they chose this
suffix. Therefore, it is likely that files with this suffix are not
all the same format; specifically, the <filename>.fnt</filename>
files used by syscons under FreeBSD may not be the same format as a
<filename>.fnt</filename> file one encounters in the MSDOS/Windows
environment. I have not made any attempt at using other
<filename>.fnt</filename> files other than those provided with
FreeBSD.</para>
</chapter>
<chapter>
<title>Setting a virtual console to 80x60 line mode</title>
<para>First, a 8x8 font must be loaded.
<filename>/etc/sysconfig</filename> should contain the lines:
<informalexample>
<programlisting># Choose font 8x8 from /usr/share/syscons/fonts/* (or NO for default)
font8x8=/usr/share/syscons/fonts/cp437-8x8.fnt</programlisting>
</informalexample>
</para>
<para>The command to actually switch the mode is
<citerefentry><refentrytitle>vidcontrol</><manvolnum>1</></>:
<informalexample>
<screen>bash$ <userinput>vidcontrol VGA_80x60</userinput></screen>
</informalexample>
</para>
<para>Various screen orientated programs, such as
<citerefentry><refentrytitle>vi</><manvolnum>1</></>, must be able to
determine the current screen dimensions. These can be set with
<citerefentry><refentrytitle>stty</><manvolnum>1</></>:
<informalexample>
<screen>bash$ <userinput>stty crt rows 60 columns 80</userinput></screen>
</informalexample>
</para>
<para>To make this more seamless, one can embed these commands in the
startup scripts so it takes place when the system boots. One way to
do this is:
<orderedlist>
<listitem>
<para>Modify <filename>/etc/sysconfig</filename> as above</para>
</listitem>
<listitem>
<para>Add to <filename>/etc/rc.local</filename>:
<informalexample>
<programlisting>for tty in /dev/ttyv?
do
vidcontrol VGA_80x60 &lt;$tty &gt;/dev/null 2&gt;&amp;1
done</programlisting>
</informalexample></para>
</listitem>
<listitem>
<para>Add to <filename>/etc/profile</filename>:
<informalexample>
<programlisting>TTYNAME=`basename \`tty\``
if expr "$TTYNAME" : 'ttyv' &gt;/dev/null
then
stty crt rows 60 columns 80
fi</programlisting>
</informalexample>
</para>
</listitem>
</orderedlist>
</para>
<para>References:
<citerefentry><refentrytitle>stty</><manvolnum>1</></>,
<citerefentry><refentrytitle>vidcontrol</><manvolnum>1</></>.</para>
</chapter>
<chapter>
<title>Using type 1 fonts with X11</title>
<para>X11 can use either the <filename>.pfa</filename> or the
<filename>.pfb</filename> format fonts. The X11 fonts are located in
various subdirectories under
<filename>/usr/X11R6/lib/X11/fonts</filename>. Each font file is
cross referenced to its X11 name by the contents of the
<filename>fonts.dir</filename> file in each directory.</para>
<para>There is already a directory named <filename>Type1</>. The most
straight forward way to add a new font is to put it into this
directory. A better way is to keep all new fonts in a separate
directory and use a symbolic link to the additional font. This
allows one to more easily keep track of ones fonts without confusing
them with the fonts that were originally provided. For
example:
<informalexample>
<screen><lineannotation>Create a directory to contain the font files</>
bash$ <userinput>mkdir -p /usr/local/share/fonts/type1</>
bash$ <userinput>cd /usr/local/share/fonts/type1</>
<lineannotation>Place the .pfa, .pfb and .afm files here</>
<lineannotation>One might want to keep readme files, and other documentation</>
<lineannotation>for the fonts here also</>
bash$ <userinput>cp /cdrom/fonts/atm/showboat/showboat.pfb .</>
bash$ <userinput>cp /cdrom/fonts/atm/showboat/showboat.afm .</>
<lineannotation>Maintain an index to cross reference the fonts</>
bash$ <userinput>echo showboat - InfoMagic CICA, Dec 1994, /fonts/atm/showboat &gt;&gt;INDEX</></screen>
</informalexample>
</para>
<para>Now, to use a new font with X11, one must make the font file
available and update the font name files. The X11 font names look
like:
<informalexample>
<screen>-bitstream-charter-medium-r-normal-xxx-0-0-0-0-p-0-iso8859-1
| | | | | | | | | | | | \ \
| | | | | \ \ \ \ \ \ \ +----+- character set
| | | | \ \ \ \ \ \ \ +- average width
| | | | \ \ \ \ \ \ +- spacing
| | | \ \ \ \ \ \ +- vertical res.
| | | \ \ \ \ \ +- horizontal res.
| | | \ \ \ \ +- points
| | | \ \ \ +- pixels
| | | \ \ \
foundry family weight slant width additional style</screen>
</informalexample>
</para>
<para>A new name needs to be created for each new font. If you have
some information from the documentation that accompanied the font,
then it could serve as the basis for creating the name. If there is
no information, then you can get some idea by using
<citerefentry><refentrytitle>strings</><manvolnum>1</></> on the font
file. For example:
<informalexample>
<screen>bash$ <userinput>strings showboat.pfb | more</>
%!FontType1-1.0: Showboat 001.001
%%CreationDate: 1/15/91 5:16:03 PM
%%VMusage: 1024 45747
% Generated by Fontographer 3.1
% Showboat
1991 by David Rakowski. Alle Rechte Vorbehalten.
FontDirectory/Showboat known{/Showboat findfont dup/UniqueID known{dup
/UniqueID get 4962377 eq exch/FontType get 1 eq and}{pop false}ifelse
{save true}{false}ifelse}{false}ifelse
12 dict begin
/FontInfo 9 dict dup begin
/version (001.001) readonly def
/FullName (Showboat) readonly def
/FamilyName (Showboat) readonly def
/Weight (Medium) readonly def
/ItalicAngle 0 def
/isFixedPitch false def
/UnderlinePosition -106 def
/UnderlineThickness 16 def
/Notice (Showboat
1991 by David Rakowski. Alle Rechte Vorbehalten.) readonly def
end readonly def
/FontName /Showboat def
--stdin--</screen>
</informalexample></para>
<para>Using this information, a possible name might be:
<informalexample>
<screen>-type1-Showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1</screen>
</informalexample>
</para>
<para>The components of our name are:
<variablelist>
<varlistentry><term>Foundry</term>
<listitem>
<para>Lets just name all the new fonts <literal>type1</>.</para>
</listitem>
</varlistentry>
<varlistentry><term>Family</term>
<listitem>
<para>The name of the font.</para>
</listitem>
</varlistentry>
<varlistentry><term>Weight</term>
<listitem>
<para>Normal, bold, medium, semibold, etc. From the
<citerefentry><refentrytitle>strings</><manvolnum>1</></> output
above, it appears that this font has a weight of
<emphasis>medium</emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry><term>Slant</term>
<listitem>
<para><emphasis remap=bf>r</emphasis>oman, <emphasis
remap=bf>i</emphasis>talic, <emphasis remap=bf>o</emphasis>blique,
etc. Since the <emphasis>ItalicAngle</emphasis> is zero,
<emphasis>roman</emphasis> will be used.</para>
</listitem>
</varlistentry>
<varlistentry><term>Width</term>
<listitem>
<para>Normal, wide, condensed, extended, etc. Until it can be examined,
the assumption will be <emphasis>normal</emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry><term>Additional style</term>
<listitem>
<para>Usually omitted, but this will indicate that
the font contains decorative capital letters.</para>
</listitem>
</varlistentry>
<varlistentry><term>Spacing</term>
<listitem>
<para>proportional or monospaced. <emphasis>Proportional</emphasis>
is used since <emphasis>isFixedPitch</emphasis> is false.</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>All of these names are arbitrary, but one should strive to be
compatible with the existing conventions. A font is referenced by
name with possible wild cards by an X11 program, so the name chosen
should make some sense. One might begin by simply using
<informalexample>
<screen>&hellip;-normal-r-normal-&hellip;-p-&hellip;</screen>
</informalexample>
as the name, and then use
<citerefentry><refentrytitle>xfontsel</><manvolnum>1</></> to examine it
and adjust the name based on the appearance of the font.</para>
<para>So, to complete our example:
<informalexample>
<screen><lineannotation>Make the font accessible to X11</>
bash$ <userinput>cd /usr/X11R6/lib/X11/fonts/Type1</>
bash$ <userinput>ln -s /usr/local/share/fonts/type1/showboat.pfb .</>
<lineannotation>Edit fonts.dir and fonts.scale, adding the line describing the font
and incrementing the number of fonts which is found on the first line.</>
bash$ <userinput>ex fonts.dir
:1p
25
:1c
26
.
:$a
showboat.pfb -type1-showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1
.
:wq</>
<lineannotation><filename>fonts.scale</> seems to be identical to <filename>fonts.dir</>&hellip;</>
bash$ <userinput>cp fonts.dir fonts.scale</>
<lineannotation>Tell X11 that things have changed</>
bash$ <userinput>xset fp rehash</>
<lineannotation>Examine the new font</>
bash$ <userinput>xfontsel -pattern -type1-*</></screen>
</informalexample>
</para>
<para>References:
<citerefentry><refentrytitle>xfontsel</><manvolnum>1</></>,
<citerefentry><refentrytitle>xset</><manvolnum>1</></>,
<citetitle>The X Windows System in a Nutshell</>, <ulink
URL="http://www.ora.com/">O'Reilly &amp; Associates</ulink>.</para>
</chapter>
<chapter>
<title>Using type 1 fonts with Ghostscript</title>
<para>Ghostscript references a font via its <filename>Fontmap</>
file. This must be modified in a similar way to the X11
<filename>fonts.dir</filename> file. Ghostscript can use either the
<filename>.pfa</filename> or the <filename>.pfb</filename> format
fonts. Using the font from the previous example, here is how to use
it with Ghostscript:
<informalexample>
<screen><lineannotation>Put the font in Ghostscript's font directory</>
bash$ <userinput>cd /usr/local/share/ghostscript/fonts</>
bash$ <userinput>ln -s /usr/local/share/fonts/type1/showboat.pfb .</>
<lineannotation>Edit Fontmap so Ghostscript knows about the font</>
bash$ <userinput>cd /usr/local/share/ghostscript/4.01</>
bash$ <userinput>ex Fontmap
:$a
/Showboat (showboat.pfb) ; % From CICA /fonts/atm/showboat
.
:wq</>
<lineannotation>Use Ghostscript to examine the font</>
bash$ <userinput>gs prfont.ps</>
Aladdin Ghostscript 4.01 (1996-7-10)
Copyright (C) 1996 Aladdin Enterprises, Menlo Park, CA. All rights
reserved.
This software comes with NO WARRANTY: see the file PUBLIC for details.
Loading Times-Roman font from /usr/local/share/ghostscript/fonts/tir_____.pfb...
/1899520 581354 1300084 13826 0 done.
GS&gt;<userinput>Showboat DoFont</>
Loading Showboat font from /usr/local/share/ghostscript/fonts/showboat.pfb...
1939688 565415 1300084 16901 0 done.
&gt;&gt;showpage, press &lt;return&gt; to continue&lt;&lt;
&gt;&gt;showpage, press &lt;return&gt; to continue&lt;&lt;
&gt;&gt;showpage, press &lt;return&gt; to continue&lt;&lt;
GS&gt;<userinput>quit</></screen>
</informalexample>
</para>
<para>References: <filename>fonts.txt</filename> in the Ghostscript
4.01 distribution</para>
</chapter>
<chapter>
<title>Using type 1 fonts with Groff</title>
<para>Now that the new font can be used by both X11 and Ghostscript,
how can one use the new font with groff? First of all, since we are
dealing with type 1 postscript fonts, the groff device that is
applicable is the <emphasis>ps</emphasis> device. A font file must be
created for each font that groff can use. A groff font name is just
a file in <filename>/usr/share/groff_font/devps</filename>. With our
example, the font file could be
<filename>/usr/share/groff_font/devps/SHOWBOAT</filename>. The file
must be created using tools provided by groff.</para>
<para>The first tool is <command>afmtodit</>. This is not normally
installed, so it must be retrieved from the source distribution. I
found I had to change the first line of the file, so I did:
<informalexample>
<screen>bash$ <userinput>cp /usr/src/gnu/usr.bin/groff/afmtodit/afmtodit.pl /tmp</>
bash$ <userinput>ex /tmp/afmtodit.pl
:1c
#!/usr/bin/perl -P-
.
:wq</></screen>
</informalexample>
</para>
<para>This tool will create the groff font file from the metrics file
(<filename>.afm</filename> suffix.) Continuing with our
example:
<informalexample>
<screen><lineannotation>Many <filename>.afm</> files are in Mac format&hellip ^M delimited lines
We need to convert them to unix style ^J delimited lines</>
bash$ <userinput>cd /tmp</>
bash$ <userinput>cat /usr/local/share/fonts/type1/showboat.afm |
tr '\015' '\012' &gt;showboat.afm</>
<lineannotation>Now create the groff font file</>
bash$ <userinput>cd /usr/share/groff_font/devps</>
bash$ <userinput>/tmp/afmtodit.pl -d DESC -e text.enc /tmp/showboat.afm generate/textmap SHOWBOAT</></screen>
</informalexample>
</para>
<para>The font can now be referenced with the name SHOWBOAT.</para>
<para>If ghostscript is used to drive the printers on the system,
then nothing more needs to be done. However, if true postscript
printers are used, then the font must be down loaded to the printer
in order for the font to be used (unless the printer happens to have
the showboat font built in or on an accessible font disk.) The final
step is to create a down loadable font. The <command>pfbtops</> tool
is used to create the <filename>.pfa</filename> format of the font,
and the <filename>download</> file is modified to reference the new
font. The <filename>download</> file must reference the internal
name of the font. This can easily be determined from the groff font
file as illustrated:
<informalexample>
<screen><lineannotation>Create the <filename>.pfa</> font file</>
bash$ <userinput>pfbtops /usr/local/share/fonts/type1/showboat.pfb &gt;showboat.pfa</></screen>
</informalexample>
Of course, if the <filename>.pfa</filename> file is already
available, just use a symbolic link to reference it.
<informalexample>
<screen><lineannotation>Get the internal font name</>
bash$ <userinput>fgrep internalname SHOWBOAT</>
internalname Showboat
<lineannotation>Tell groff that the font must be down loaded</>
bash$ <userinput>ex download
:$a
Showboat showboat.pfa
.
:wq</></screen>
</informalexample>
</para>
<para>To test the font:
<informalexample>
<screen>bash$ <userinput>cd /tmp</>
bash$ <userinput>cat &gt;example.t &lt;&lt;EOF
.sp 5
.ps 16
This is an example of the Showboat font:
.br
.ps 48
.vs (\n(.s+2)p
.sp
.ft SHOWBOAT
ABCDEFGHI
.br
JKLMNOPQR
.br
STUVWXYZ
.sp
.ps 16
.vs (\n(.s+2)p
.fp 5 SHOWBOAT
.ft R
To use it for the first letter of a paragraph, it will look like:
.sp 50p
\s(48\f5H\s0\fRere is the first sentence of a paragraph that uses the
showboat font as its first letter.
Additional vertical space must be used to allow room for the larger
letter.
EOF</>
bash$ <userinput>groff -Tps example.t &gt;example.ps</>
<lineannotation>To use ghostscript/ghostview</>
bash$ <userinput>ghostview example.ps</>
<lineannotation>To print it</>
bash$ <userinput>lpr -Ppostscript example.ps</></screen>
</informalexample>
</para>
<para>References:
<filename>/usr/src/gnu/usr.bin/groff/afmtodit/afmtodit.man</filename>,
<citerefentry><refentrytitle>groff_font</><manvolnum>5</></>,
<citerefentry><refentrytitle>groff_char</><manvolnum>5</></>,
<citerefentry><refentrytitle>pfbtops</><manvolnum>1</></>.</para>
</chapter>
<chapter>
<title>Converting TrueType fonts to a groff/postscript format for
groff</title>
<para>This potentially requires a bit of work, simply because it
depends on some utilities that are not installed as part of the
base system. They are:</para>
<variablelist>
<varlistentry>
<term><command>ttf2pf</command></term>
<listitem>
<para>TrueType to postscript convertsion utilities. This
allows conversion of a TrueType font to an ascii font
metric (<filename>.afm</filename>) file.</para>
<para>Currently available at <ulink
url="http://sunsite.icm.edu.pl/pub/GUST/contrib/BachoTeX98/ttf2pf/">http://sunsite.icm.edu.pl/pub/GUST/contrib/BachoTeX98/ttf2pf</ulink>.
Note: These files are postscript programs and must be
downloaded to disk by holding down the
<keycap>Shift</keycap> key when clicking on the
link. Otherwise, your browser may try to launch
<application>ghostview</application> to view them.</para>
<para>The files of interest are:</para>
<itemizedlist>
<listitem>
<para><filename>GS_TTF.PS</filename></para
</listitem>
<listitem>
<para><filename>PF2AFM.PS</filename></para>
</listitem>
<listitem>
<para><filename>ttf2pf.ps</filename></para>
</listitem>
</itemizedlist>
<para>The funny upper/lower case is due to their being
intended also for DOS shells.
<filename>ttf2pf.ps</filename> makes use of the others as
upper case, so any renaming must be consistent with
this. (Actually, <filename>GS_TTF.PS</filename> and
<filename>PFS2AFM.PS</filename> are supposedly part of the
ghostscript distribution, but it's just as easy to use
these as an isolated utility. FreeBSD doesn't seem to
include the latter.) You also may want to have these
installed to
<filename>/usr/local/share/groff_font/devps</filename>(?).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>afmtodit</command></term>
<listitem>
<para>Creates font files for use with groff from ascii font
metrics file. This usually resides in the directory,
<filename>/usr/src/contrib/groff/afmtodit</filename>, and
requires some work to get going.</para>
<note>
<para> If you're paranoid about working in the
<filename>/usr/src</filename> tree, simply copy the
contents of the above directory to a work
location.</para>
</note>
<para>In the work area, you'll need to make the
utility. Just type:</para>
<screen>
<prompt>#</prompt> <userinput>make -f Makefile.sub afmtodit</userinput>
</screen>
<para>You may also need to copy
<filename>/usr/contrib/groff/devps/generate/textmap</filename>
to
<filename>/usr/share/groff_font/devps/generate</filename>
if it doesn't already exist.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Once all these utilities are in place, you're ready to
commence:</para>
<orderedlist>
<listitem>
<para>Create the <filename>.afm</filename> file by
typing:</para>
<screen>
<prompt>%</prompt> <userinput>gs <optional>-dNODISPLAY</optional> <optional>-q</optional> -- ttf2pf.ps <replaceable>TTF_name</replaceable> <optional><replaceable>PS_font_name</replaceable> <optional><replaceable>AFM_name</replaceable></optional></optional></userinput>
</screen>
<para>Where, <replaceable>TTF_name</replaceable> is your
TrueType font file, <replaceable>PS_font_name</replaceable>
is the file name for the <filename>.pfa</filename> file,
<replaceable>AFM_name</replaceable> is the name you wish for
the <filename>.afm</filename> file. If you do not specify
output file names for the <filename>.pfa</filename> or
<filename>.afm</filename> files, then default names will be
generated from the TrueType font file name.</para>
<para>This also produces a <filename>.pfa</filename> file, the
ascii postscript font metrics file
(<filename>.pfb</filename> is for the binrary form). This
won't be needed, but could (I think) be useful for a
fontserver.</para>
<para>For example, to convert the 30f9 Barcode font using the
default file names, use the following command:</para>
<screen>
<prompt>%</prompt> <userinput>gs -dNODISPLAY -- ttf2pf.ps 3of9.ttf</userinput>
Aladdin Ghostscript 5.10 (1997-11-23)
Copyright (C) 1997 Aladdin Enterprises, Menlo Park, CA. All rights reserved.
This software comes with NO WARRANTY: see the file PUBLIC for details.
Converting 3of9.ttf to 3of9.pfa and 3of9.afm.
</screen>
<para>If you want the converted fonts to be stored in
<filename>A.pfa</filename> and <filename>B.afm</filename>,
then use this command:</para>
<screen>
<prompt>%</prompt> <userinput>gs -dNODISPLAY -- ttf2pf.ps 3of9.ttf A B</userinput>
Aladdin Ghostscript 5.10 (1997-11-23)
Copyright (C) 1997 Aladdin Enterprises, Menlo Park, CA. All rights reserved.
This software comes with NO WARRANTY: see the file PUBLIC for details.
Converting 3of9.ttf to A.pfa and B.afm.
</screen>
</listitem>
<listitem>
<para>Create the groff postscript file:</para>
<para>Change directories to
<filename>/usr/share/groff_font/devps</filename> so as to
make the following command easier to execute. You'll
probably need root priviledges for this. (Or, if you're
paranoid about working there, make sure you reference the
files <filename>DESC</filename>,
<filename>text.enc</filename> and
<filename>generate/textmap</filename> as being in this
directory.)</para>
<screen>
<prompt>%</prompt> <userinput>afmtodit -d DESC -e text.enc file.afm \
generate/textmap <replaceable>PS_font_name</replaceable></userinput>
</screen>
<para>Where, <filename>file.afm</filename> is the
<replaceable>AFM_name</replaceable> created by
<command>ttf2pf.ps</command> above, and
<replaceable>PS_font_name</replaceable> is the font name
used from that command, as well as the name that
<citerefentry> <refentrytitle>groff</><manvolnum>1</></>
will use for references to this font. For example, assuming
you used the first <command>tiff2pf.ps</command> command
above, then the 3of9 Barcode font can be created using the
command:</para>
<screen>
<prompt>%</prompt> <userinput>afmtodit -d DESC -e text.enc 3of9.afm \
generate/textmap 3of9</userinput>
</screen>
<para>Ensure that the resulting
<replaceable>PS_font_name</replaceable> file (e.g.,
<filename>3of9</filename> in the example above) is located
in the directory
<filename>/usr/share/groff_font/devps</filename> by copying
or moving it there.</para>
<para>Note that if <filename>ttf2pf.ps</filename> assigns a
font name using the one it finds in the TrueType font file
and you want to use a different name, you must edit the
<filename>.afm</filename> file prior to running
<command>afmtodit</command>. This name must also match the
one used in the Fontmap file if you wish to pipe
<citerefentry><refentrytitle>groff</><manvolnum>1</></> into
<citerefentry><refentrytitle>gs</><manvolnum>1</></>.</para>
</listitem>
</orderedlist>
</chapter>
<chapter>
<title>Can TrueType fonts be used with other programs?</title>
<para>The TrueType font format is used by Windows, Windows 95, and
Mac's. It is quite popular and there are a great number of
fonts available in this format.</para>
<para>Unfortunately, there are few applications that I am aware of
that can use this format: Ghostscript and Povray come to mind.
Ghostscript's support, according to the documentation, is rudimentary
and the results are likely to be inferior to type 1 fonts.
Povray version 3 also has the ability to use TrueType fonts, but
I rather doubt many people will be creating documents as a series of
raytraced pages :-).</para>
<para>This rather dismal situation may soon change.
The <ulink url="http://www.freetype.org/">FreeType Project</ulink>
is currently developing a useful set of FreeType tools:
<itemizedlist>
<listitem>
<simpara>The <command>xfsft</command> font server for X11 can serve
TrueType fonts in addition to regular fonts. Though currently in
beta, it is said to be quite useable. See <ulink
url="http://www.dcs.ed.ac.uk/home/jec/programs/xfsft/">Juliusz
Chroboczek's page</ulink> for further information. Porting instructions
for FreeBSD can be found at <ulink
url="http://math.missouri.edu/~stephen/software/">Stephen Montgomery's
software page</ulink>.
</simpara>
</listitem>
<listitem>
<simpara><command>xfstt</command> is another font
server for X11, available under <ulink
url=" ftp://sunsite.unc.edu/pub/Linux/X11/fonts">
ftp://sunsite.unc.edu/pub/Linux/X11/fonts</ulink>.
</simpara>
</listitem>
<listitem><simpara>A program called <command>ttf2bdf</command> can produce
BDF files suitable for use in an X environment from TrueType files. Linux
binaries are said to be available from <ulink
url="ftp://crl.nmsu.edu/CLR/multiling/General">ftp://crl.nmsu.edu/CLR/multiling/General/</ulink>.
</simpara>
</listitem>
<listitem>
<simpara>
For people requiring the use of Asian TrueType fonts, the
<command>XTT</command> font server may be worth a look. Information about
<command>XTT</command> can be found at URL: <ulink
url="http://hawk.ise.chuo-u.ac.jp/student/person/tshiozak/study/freebsd-at-random/x-tt/index-en.html">http://hawk.ise.chuo-u.ac.jp/student/person/tshiozak/study/freebsd-at-random/x-tt/index-en.html</ulink>.
</simpara>
</listitem>
<listitem>
<simpara>and others &hellip;</simpara>
</listitem>
</itemizedlist>
</para>
<para>
The
<ulink url="http://www.freetype.org/projects.htm">FreeType Projects page
</ulink> is a good starting point for information on these and other
free TrueType projects.
</para>
</chapter>
<chapter>
<title>Where can additional fonts be obtained?</title>
<para>Many fonts are available on the Internet. They are either
entirely free, or are share-ware. In addition, there are many
inexpensive CDROMs available that contain many fonts. Some Internet
locations (as of August 1996) are:
<itemizedlist>
<listitem><para><ulink
url="ftp://ftp.winsite.com">ftp://ftp.winsite.com</ulink> (Formerly
CICA)</para></listitem>
<listitem><para><ulink
url="http://www.simtel.net/simcgi-bin/dosfind.cgi">http://www.simtel.net/simcgi-bin/dosfind.cgi</ulink></para></listitem>
<listitem><para><ulink
url="ftp://ftp.coast.net/">ftp://ftp.coast.net/</ulink></para></listitem>
<listitem><para><ulink
url="http://af-pc-plloyd.ecel.uwa.edu.au/fonts/index.html">http://af-pc-plloyd.ecel.uwa.edu.au/fonts/index.html</ulink></para></listitem>
<listitem><para><ulink
url="http://www.esselte.com/letraset/index.html">http://www.esselte.com/letraset/index.html</ulink></para></listitem>
<listitem><para><ulink
url="http://www.inil.com/users/elfring/esf.htm">http://www.inil.com/users/elfring/esf.htm</ulink></para></listitem>
</itemizedlist></para>
</chapter>
<chapter>
<title>Additional questions</title>
<para>
<itemizedlist>
<listitem>
<para>What use are the <filename>.pfm</filename> files?</para>
</listitem>
<listitem>
<para>Can one generate the <filename>.afm</filename> file from a <filename>.pfa</filename> or <filename>.pfb</filename>?</para>
</listitem>
<listitem>
<para>How to generate the groff character mapping files for postscript fonts
with non-standard character names?</para>
</listitem>
<listitem>
<para>Can xditview and devX?? devices be setup to access all the new fonts?</para>
</listitem>
<listitem>
<para>It would be good to have examples of using TrueType fonts with povray and
ghostscript.</para>
</listitem>
</itemizedlist>
</para>
</chapter>
</book>

58
en/tutorials/index.sgml
View file

@ -1,58 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN" [
<!ENTITY base CDATA "..">
<!ENTITY date "$Date: 1999-04-26 21:50:42 $">
<!ENTITY title "FreeBSD Tutorials">
<!ENTITY % includes SYSTEM "../includes.sgml"> %includes;
]>
<!-- $Id: index.sgml,v 1.20 1999-04-26 21:50:42 nik Exp $ -->
<html>
&header;
<p>Here lie assorted documents on various aspects of FreeBSD,
FreeBSD software, and hardware. If you have comments or
would like to contribute a document, please contact us at
<a href="mailto:freebsd-doc@FreeBSD.ORG">freebsd-doc@FreeBSD.org</a>.</p>
<ul>
<li><a href="newuser/newuser.html">For People New to Both FreeBSD
<em>and</em> Unix</a></li>
<li><a href="mh/mh.html">An introduction to the MH mail software</a></li>
<li><a href="devel/devel.html">A User's Guide to FreeBSD Programming
Tools</a></li>
<li><a href="ddwg/ddwg.html">Writing device drivers for FreeBSD</a>
(<a href="ddwg/ddwg.ps">postscript</a>,
<a href="ddwg/ddwg-html.tar.gz">gzipd tar file</a>)</li>
<li><a href="ppp/ppp.html">Pedantic PPP primer - IP Aliasing</a>
(<a href="ppp/ppp.ps">postscript</a>,
<a href="ppp/ppp-html.tar.gz">gzipd tar file</a>)</li>
<li><a href="multios/multios.html">Using FreeBSD with other operating systems</a></li>
<li><a href="fonts/fonts.html">Fonts and FreeBSD</a></li>
<li><a href="http://www.cypher.net/~black/ipalias.html">IP Aliasing</a></li>
<li><a href="http://www.nothing-going-on.demon.co.uk/FreeBSD/make-world/make-world.html">Upgrading FreeBSD from source (using <b><tt>make world</tt></b>)</a></li>
<li><a href="diskformat/diskformat.html">Formatting Media For Use With FreeBSD
2.2-RELEASE</a></li>
<li><a href="http://www.users.globalnet.co.uk/~markov/ntfs_install.html">Installing the FreeBSD NTFS (NT Filesystem) driver</a></li>
<li><a href="http://www.freebsd.org/~rpratt/227/">FreeBSD 2.2.7 Installation Details for Newbies</a>
<li><a href="&base;/tutorials/docproj-primer/">FreeBSD Documentation
Project Primer</a> (many small HTML files)</li>
<li><a href="&base;/tutorials/docproj-primer/book.html">FreeBSD
Documentation Project Primer</a> (one large HTML file)</li>
</ul>
&footer;
</body>
</html>

7
en/tutorials/mh/Makefile
View file

@ -1,7 +0,0 @@
# $Id: Makefile,v 1.4 1997-07-01 05:38:13 max Exp $
DOCS= mh.docb
INDEXLINK= mh.html
.include "../../web.mk"

704
en/tutorials/mh/mh.docb
View file

@ -1,704 +0,0 @@
<!-- $Id: mh.docb,v 1.2 1997-07-01 21:38:44 max Exp $ -->
<!-- FreeBSD Documentation Project -->
<!DOCTYPE BOOK PUBLIC "-//Davenport//DTD DocBook V3.0//EN">
<book>
<bookinfo>
<bookbiblio>
<title>An MH Primer</title>
<authorgroup>
<author>
<firstname>Matt</firstname>
<surname>Midboe</surname>
<affiliation>
<address>
<email>matt@garply.com</email>
</address>
</affiliation>
</author></authorgroup>
<pubdate>v1.0, 16 January 1996</pubdate>
<abstract><para>This document contains an introduction to using MH on
FreeBSD</para></abstract>
</bookbiblio>
</bookinfo>
<chapter id="mhintro">
<title>Introduction</title>
<para>MH started back in 1977 at the RAND Corporation, where the
initial philosophies behind MH were developed. MH isn't so much a
monolithic email program but a philosophy about how best to develop
tools for reading email. The MH developers have done a great job
adhering to the <acronym>KISS</> principle: Keep It Simple Stupid.
Rather than have one large program for reading, sending and handling
email they have written specialized programs for each part of your
email life. One might liken MH to the specialization that one finds
in insects and nature. Each tool in MH does one thing, and does it
very well.</para>
<para>Beyond just the various tools that one uses to handle their
email MH has done an excellent job keeping the configuration of each
of these tools consistent and uniform. In fact, if you are not quite
sure how something is supposed to work or what the arguments for some
command are supposed to be then you can generally guess and be right.
Each MH command is consistent about how it handles reading the
configuration files and how it takes arguments on the command line.
One useful thing to remember is that you can always add a
<option>-help</option> to the command to have it display the options
for that command.</para>
<para>The first thing that you need to do is to make sure that you have
installed the MH package on your FreeBSD machine. If you installed
from CDROM you should be able to execute the following to load mh:
<informalexample>
<screen># <userinput>pkg_add /cdrom/packages/mh-6.8.3.tgz</></screen>
</informalexample>
You will notice that it created a <filename>/usr/local/lib/mh</>
directory for you as well as adding several binaries to the
<filename>/usr/local/bin</> directory. If you would prefer to compile
it yourself then you can anonymous ftp it from <ulink
URL="ftp://ftp.ics.uci.edu/">ftp.ics.uci.edu</ulink> or <ulink
URL="ftp://louie.udel.edu/">louie.udel.edu</ulink>.</para>
<para>This primer is not a full comprehensive explanation of how MH
works. This is just intended to get you started on the road to
happier, faster mail reading. You should read the man pages for the
various commands. Also you might want to read the <ulink
URL="news:comp.mail.mh">comp.mail.mh</ulink> newsgroup. Also you can
read the <ulink
URL="http://www.cis.ohio-state.edu/hypertext/faq/usenet/mh-faq/part1/faq.html">FAQ
for MH</ulink>. The best resource for MH is the O'Reilly and Associates book
written by Jerry Peek.</para>
</chapter>
<chapter>
<title>Reading Mail</title>
<para>This section covers how to use <command>inc</>,
<command>show</>, <command>scan</>, <command>next</>,
<command>prev</>, <command>rmm</>, <command>rmf</>, and
<command>msgchk</>. One of the best things about MH is the
consistent interface between programs. A few things to keep in mind
when using these commands is how to specify message lists. In the
case of <command>inc</> this doesn't really make any sense but with
commands like <command>show</> it is useful to know. </para>
<para>A message list can consist of something like <parameter>23 20
16</> which will act on messages 23, 20 and 16. This is fairly simple
but you can do more useful things like <parameter>23-30</> which will
act on all the messages between 23 and 30. You can also specify
something like <parameter>cur:10</> which will act on the current
message and the next 9 messages. The <parameter>cur</>,
<parameter>last</>, and <parameter>first</> messages are special
messages that refer to the current, last or first message in the
folder.</para>
<sect1 id="inc">
<title><command>inc</>, <command>msgchk</>&mdash;read in your new email or check it</title>
<para>If you just type in <userinput>inc</> and hit <keycap>return</>
you will be well on your way to getting started with MH. The first
time you run <command>inc</> it will setup your account to use all
the MH defaults and ask you about creating a Mail directory. If you
have mail waiting to be downloaded you will see something that looks
like:
<informalexample>
<screen> 29 01/15 Doug White Re: Another Failed to boot problem&lt;&lt;On Mon, 15 J
30 01/16 "Jordan K. Hubbar Re: FBSD 2.1&lt;&lt;&gt; Do you want a library instead of
31 01/16 Bruce Evans Re: location of bad144 table&lt;&lt;&gt;&gt; &gt;It would appea
32 01/16 "Jordan K. Hubbar Re: video is up&lt;&lt;&gt; Anyway, mrouted won't run, ev
33 01/16 Michael Smith Re: FBSD 2.1&lt;&lt;Nate Williams stands accused of sa</screen>
</informalexample>
This is the same thing you will see from a <command>scan</> (see
<xref linkend="scan">). If you just run <command>inc</> with no
arguments it will look on your computer for email that is supposed to
be coming to you.</para>
<para>A lot of people like to use POP for grabbing their email. MH can do
POP to grab your email. You will need to give <command>inc</> a few command
line arguments.
<informalexample>
<screen>tempest% <userinput>inc -host mail.pop.org -user <replaceable>username</> -norpop</></screen>
</informalexample>
That tells <command>inc</> to go to <parameter>mail.pop.org</> to
download your email, and that your username on their system is
<replaceable>username</>. The <option>-norpop</option> option tells
<command>inc</> to use plain POP3 for downloading your email. MH has
support for a few different dialects of POP. More than likely you
will never ever need to use them though. While you can do more
complex things with inc such as audit files and scan format files
this will get you going.</para>
<para>The <command>msgchk</> command is used to get information on
whether or not you have new email. <command>msgchk</> takes the same
<option>-host</option> and <option>-user</option> options that
<command>inc</> takes.</para>
</sect1>
<sect1 id="show">
<title><command>show</>, <command>next</> and <command>prev</>&mdash;displaying and moving through email</title>
<para><command>show</> is to show a letter in your current folder.
Like <command>inc</>, <command>show</> is a fairly straightforward
command. If you just type <userinput>show</> and hit <keycap>return</>
then it displays the current message. You can also give specific
message numbers to show:
<informalexample>
<screen>tempest% <userinput>show 32 45 56</></screen>
</informalexample>
This would display message numbers 32, 45 and 56 right after each
other. Unless you change the default behavior <command>show</>
basically just does a <command>more</> on the email message.</para>
<para><command>next</> is used to move onto the next message and
<command>prev</> will go to the previous message. Both commands have
an implied <command>show</> command so that when you go to the next
message it automatically displays it.</para>
</sect1>
<sect1 id="scan">
<title><command>scan</>&mdash;shows you a scan of your messages</title>
<para><command>scan</> will display a brief listing of the messages
in your current folder. This is an example of what the
<command>scan</> command will give you.
<informalexample>
<screen> 30+ 01/16 "Jordan K. Hubbar Re: FBSD 2.1&lt;&lt;&gt; Do you want a library instead of
31 01/16 Bruce Evans Re: location of bad144 table&lt;&lt;&gt;&gt; &gt;It would appea
32 01/16 "Jordan K. Hubbar Re: video is up&lt;&lt;&gt; Anyway, mrouted won't run, ev
33 01/16 Michael Smith Re: FBSD 2.1&lt;&lt;Nate Williams stands accused of sa</screen>
</informalexample>
Like just about everything in MH this display is very configurable.
This is the typical default display. It gives you the message number,
the date on the email, the sender, the subject line, and a sentence
fragment from the very beginning of the email if it can fit it. The
<literal>+</> means that message is the current message, so if you do
a <command>show</> it will display that message.</para>
<para>One useful option for scan is the <option>-reverse</option>
option. This will list your messages with the highest message number
first and lowest message number last. Another useful option with
<command>scan</> is to have it read from a file. If you want to scan
your incoming mailbox on FreeBSD without having to <command>inc</> it
you can do <command>scan -file
/var/mail/<replaceable>username</></command>. This can be used with
any file that is in the <database>mbox</> format.</para>
</sect1>
<sect1 id="rmm">
<title><command>rmm</> and <command>rmf</>&mdash;remove the current message or folder</title>
<para><command>rmm</> is used to remove a mail message. The default
is typically to not actually remove the message but to rename the
file to one that is ignored by the MH commands. You will need to
through periodically and physically delete the <quote>removed</>
messages.</para>
<para>The <command>rmf</> command is used to remove folders. This
doesn't just rename the files but actually removes the from the hard
drive so you should be careful when you use this command.</para>
</sect1>
<sect1 id="samplereading">
<title>A typical session of reading with MH</title>
<para>The first thing that you will want to do is <command>inc</>
your new mail. So at a shell prompt just type in <command>inc</> and
hit <keycap>return</>.
<informalexample>
<screen>tempest% <userinput>inc</>
Incorporating new mail into inbox...
36+ 01/19 "Stephen L. Lange Request...&lt;&lt;Please remove me as contact for pind
37 01/19 Matt Thomas Re: kern/950: Two PCI bridge chips fail (multipl
38 01/19 "Amancio Hasty Jr Re: FreeBSD and VAT&lt;&lt;&gt;&gt;&gt; Bill Fenner said: &gt; In
tempest%</screen>
</informalexample>
This shows you the new email that has been added to your mailbox. So
the next thing to do is <command>show</> the email and move around.
<informalexample>
<screen>tempest% <userinput>show</>
Received: by sashimi.wwa.com (Smail3.1.29.1 #2)
id m0tdMZ2-001W2UC; Fri, 19 Jan 96 13:33 CST
Date: Fri, 19 Jan 1996 13:33:31 -0600 (CST)
From: "Stephen L. Lange" &lt;stvlange@wwa.com&gt;
To: matt@garply.com
Subject: Request...
Message-Id: &lt;Pine.BSD.3.91.960119133211.824A-100000@sashimi.wwa.com&gt;
Mime-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII
Please remove me as contact for pindat.com
tempest% <userinput>rmm</>
tempest% <userinput>next</>
Received: from localhost (localhost [127.0.0.1]) by whydos.lkg.dec.com (8.6.11/8
.6.9) with SMTP id RAA24416; Fri, 19 Jan 1996 17:56:48 GMT
Message-Id: &lt;199601191756.RAA24416@whydos.lkg.dec.com&gt;
X-Authentication-Warning: whydos.lkg.dec.com: Host localhost didn't use HELO pro
tocol
To: hsu@clinet.fi
Cc: hackers@FreeBSD.org
Subject: Re: kern/950: Two PCI bridge chips fail (multiple multiport ethernet
boards)
In-Reply-To: Your message of "Fri, 19 Jan 1996 00:18:36 +0100."
&lt;199601182318.AA11772@Sysiphos&gt;
X-Mailer: exmh version 1.5omega 10/6/94
Date: Fri, 19 Jan 1996 17:56:40 +0000
From: Matt Thomas &lt;matt@lkg.dec.com&gt;
Sender: owner-hackers@FreeBSD.org
Precedence: bulk
This is due to a typo in pcireg.h (to
which I am probably the guilty party).</screen>
</informalexample></para>
<para>The <command>rmm</> removed the current message and the
<command>next</> command moved me on to the next message.
Now if I wanted to look at ten most recent messages so I could read
one of them here is what I would do:
<informalexample>
<screen>tempest% <userinput>scan last:10</>
26 01/16 maddy Re: Testing some stuff&lt;&lt;yeah, well, Trinity has
27 01/17 Automatic digest NET-HAPPENINGS Digest - 16 Jan 1996 to 17 Jan 19
28 01/17 Evans A Criswell Re: Hey dude&lt;&lt;&gt;From matt@tempest.garply.com Tue
29 01/16 Karl Heuer need configure/make volunteers&lt;&lt;The FSF is looki
30 01/18 Paul Stephanouk Re: [alt.religion.scientology] Raw Meat (humor)&lt;
31 01/18 Bill Lenherr Re: Linux NIS Solaris&lt;&lt;--- On Thu, 18 Jan 1996 1
34 01/19 John Fieber Re: Stuff for the email section?&lt;&lt;On Fri, 19 Jan
35 01/19 support@foo.garpl [garply.com #1138] parlor&lt;&lt;Hello. This is the Ne
37+ 01/19 Matt Thomas Re: kern/950: Two PCI bridge chips fail (multipl
38 01/19 "Amancio Hasty Jr Re: FreeBSD and VAT&lt;&lt;&gt;&gt;&gt; Bill Fenner said: &gt; In
tempest%</screen>
</informalexample>
Then if I wanted to read message number 27 I would do a
<userinput>show 27</> and it would be displayed. As you can probably
tell from this sample session MH is pretty easy to use and looking
through emails and displaying them is fairly intuitive and easy.
</para>
</sect1>
</chapter>
<chapter>
<title>Folders and Mail Searching</title>
<para>Anybody who gets lots of email definitely wants to be able to
prioritize, stamp, brief, de-brief, and number their emails in a
variety of different ways. MH can do this better than just about
anything. One thing that we haven't really talked about is the
concept of folders. You have undoubtedly come across the folders
concept using other email programs. MH has folders too. MH can even
do sub-folders of a folder. One thing you should keep in mind with MH
is that when you ran <command>inc</> for the first time and it asked
you if it could create a <filename>Mail</> directory it began storing
everything in that directory. If you look at that directory you will
find a directory named <filename>inbox</>. The <filename>inbox</>
directory houses all of your incoming mail that hasn't been thrown
anywhere else.</para>
<para>Whenever you create a new folder a new directory is going to be
created underneath your MH <filename>Mail</> directory, and messages
in that folder are going to be stored in that directory. When new
email comes in that new email is thrown into your <filename>inbox</>
directory with a file name that is equivalent to the message number.
So even if you didn't have any of the MH tools to read your email you
could still use standard UNIX commands to munge around in those
directories and just more your files. It's this simplicity that
really gives you a lot of power with what you can do with your
email.</para>
<para>Just as you can use message lists like <parameter>23 16 42</>
with most MH commands there is a folder option you can specify with
just about every MH command. If you do a <command>scan +freebsd</> it
will scan your <filename>freebsd</> folder, and your current folder
will be changed to <filename>freebsd</>. If you do a <command>show
+freebsd 23 16 42</>, <command>show</> is going to switch to your
<filename>freebsd</> folder and display messages 23, 16 and 42. So
remember that <option>+<replaceable>folder</></> syntax. You will
need to make sure you use it to make commands process different
folders. Remember you default folder for mail is <filename>inbox</>
so doing a <command>folder +inbox</> should always get you back to
your mail. Of course, in MH's infinite flexibility this can be
changed but most places have probably left it as
<command>inbox</>.</para>
<sect1>
<title><command>pick</>&mdash;search email that matches certain criteria</title>
<para><command>pick</> is one of the more complex commands in the MH
system. So you might want to read the
<citerefentry><refentrytitle>pick</><manvolnum>1</></> man page for a
more thorough understanding. At its simplest level you can do
something like
<informalexample>
<screen>tempest% <userinput>pick -search pci</>
15
42
55
56
57</screen>
</informalexample>
This will tell <command>pick</> to look through every single line in
every message in your current folder and tell you which message
numbers it found the word <literal>pci</> in. You can then
<command>show</> those messages and read them if you wish or
<command>rmm</> them. You would have to specify something like
<command>show 15 42 55-57</> to display them though. A slightly more
useful thing to do is this:
<informalexample>
<screen>tempest% <userinput>pick -search pci -seq pick</>
5 hits
tempest% <userinput>show pick</></screen>
</informalexample>
This will show you the same messages you just didn't have to work as
hard to do it. The <option>-seq</option> option is really an
abbreviation of <option>-sequence</option> and <command>pick</> is
just a sequence which contains the message numbers that matched. You
can use sequences with just about any MH command. So you could have
done an <command>rmm pick</> and all those messages would be removed
instead. You sequence can be named anything. If you run pick again it
will overwrite the old sequence if you use the same name.</para>
<para>Doing a <command>pick -search</command> can be a bit more time
consuming than just searching for message from someone, or to
someone. So <command>pick</> allows you to use the following
predefined search criteria:
<variablelist>
<varlistentry>
<term><option>-to</option></term>
<listitem>
<para>search based upon who the message is to</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-cc</option></term>
<listitem>
<para>search based on who is in the cc list</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-from</option></term>
<listitem>
<para>search for who sent the message</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-subject</option></term>
<listitem>
<para>search for emails with this subject</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-date</option></term>
<listitem>
<para>find emails with a matching dat</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--<replaceable>component</replaceable></option></term>
<listitem>
<para>search for any other component in the header. (i.e.
<option>--reply-to</> to find all emails with a certain reply-to in
the header)</para>
</listitem>
</varlistentry>
</variablelist></para>
<para>This allows you to do things like
<informalexample>
<screen>tempest% <userinput>pick -to freebsd-hackers@freebsd.org -seq hackers</></screen>
</informalexample>
to get a list of all the email send to the FreeBSD hackers mailing
list. <command>pick</> also allows you to group these criteria in
different ways using the following options:
<itemizedlist>
<listitem>
<para>&hellip; <option>-and</option> &hellip;</para>
</listitem>
<listitem>
<para>&hellip; <option>-or</option> &hellip</para>
</listitem>
<listitem>
<para><option>-not</option> &hellip;</para>
</listitem>
<listitem>
<para><option>-lbrace</option> &hellip; <option>-rbrace</option></para>
</listitem>
</itemizedlist>
These commands allow you to do things like
<informalexample>
<screen>tempest% <userinput>pick -to freebsd-hackers -and -cc freebsd-hackers</></screen>
</informalexample>
That will grab all the email in your inbox that was sent to
freebsd-hackers or cc'd to that list. The brace options allow you to
group search criteria together. This is sometimes very necessary as
in the following example
<informalexample>
<screen>tempest% <userinput>pick -lbrace -to freebsd-hackers -and
-not -cc freebsd-questions -rbrace -and -subject pci</></screen>
</informalexample></para>
<para>Basically this says <quote>pick (to freebsd-hackers and not cc'd on
freebsd-questions) and the subject is pci</quote>. It should look through your
folder and find all messages sent to the freebsd-hackers list that
aren't cc'd to the freebsd-questions list that contain something on
pci in the subject line. Ordinarily you might have to worry about
something called operator precedence. Remember in math how you
evaluate from left to right and you do multiplication and division
first and addition and subtraction second? MH has the same type of
rules for <command>pick</>. It's fairly complex so you might want to study
the man page. This document is just to help you get acquainted with
MH.</para>
</sect1>
<sect1>
<title><command>folder</>, <command>folders</>, <command>refile</>&mdash;three useful programs for folder maintenance</title>
<para>There are three programs which are primarily just for
manipulating your folders. The <command>folder</> program is used to
switch between folders, pack them, and list them. At its simplest
level you can do a <command>folder +<replaceable>newfolder</></> and
you will be switched into <replaceable>newfolder</>. From there on
out all your MH commands like <command>comp</>, <command>repl</>,
<command>scan</>, and <command>show</> will act on that
<command>newfolder</> folder.</para>
<para>Sometimes when you are reading and deleting messages you will
develop <quote>holes</> in your folders. If you do a <command>scan</>
you might just see messages 34, 35, 36, 43, 55, 56, 57, 80. If you do
a <command>folder -pack</command> this will renumber all your
messages so that there are no holes. It doesn't actually delete any
messages though. So you may need to periodically go through and
physically delete <command>rmm</>'d messages.</para>
<para>If you need statistics on your folders you can do a
<command>folders</> or <command>folder -all</command> to list all
your folders, how many messages they have, what the current message
is in each one and so on. This line of stats it displays for all your
folders is the same one you get when you change to a folder with
<command>folder +foldername</>. A <command>folders</> command looks
like this:
<informalexample>
<screen> Folder # of messages ( range ); cur msg (other files)
announce has 1 message ( 1- 1).
drafts has no messages.
f-hackers has 43 messages ( 1- 43).
f-questions has 16 messages ( 1- 16).
inbox+ has 35 messages ( 1- 38); cur= 37.
lists has 8 messages ( 1- 8).
netfuture has 1 message ( 1- 1).
out has 31 messages ( 1- 31).
personal has 6 messages ( 1- 6).
todo has 58 messages ( 1- 58); cur= 1.
TOTAL= 199 messages in 13 folders.
</screen>
</informalexample></para>
<para>The <command>refile</> command is what you use to move messages
between folders. When you do something like <command>refile 23
+netfuture</> message number 23 is moved into the
<filename>netfuture</> folder. You could also do something like
<command>refile 23 +netfuture/latest</> which would put message
number 23 in a subfolder called <filename>latest</> under the
<filename>netfuture</> folder. If you want to keep a message in the
current folder and link it you can do a <command>refile -link 23
+netfuture</command> which would keep 23 in your current
<filename>inbox</> but also list in your <filename>netfuture</>
folder. You are probably beginning to realize some of the really
powerful things you can do with MH.</para>
</sect1>
</chapter>
<chapter>
<title>Sending Mail</title>
<para>Email is a two way street for most people so you want to be
able to send something back. The way MH handles sending mail can be a
bit difficult to follow at first, but it allows for incredible
flexibility. The first thing MH does is to copy a components file
into your outgoing email. A components file is basically a skeleton
email letter with stuff like the To: and Subject: headers already in
it. You are then sent into your editor where you fill in the header
information and then type the body of your message below the dashed
lines in the message. Then to the <command>whatnow</> program. When
you are at the <prompt>What now?</prompt> prompt you can tell it to
<command>send</>, <command>list</>, <command>edit</>,
<command>edit</>, <command>push</>, and <command>quit</>. Most of
these commands are self-explanatory. So the message sending process
involves copying a component file, editing your email, and then
telling the <command>whatnow</> program what to do with your
email.</para>
<sect1>
<title><command>comp</>, <command>forw</>, <command>reply</>&mdash;compose, forward or reply to a message to someone</title>
<para>The <command>comp</> program has a few useful command line
options. The most important one to know right now is the
<option>-editor</option> option. When MH is installed the default
editor is usually a program called <command>prompter</> which comes
with MH. It's not a very exciting editor and basically just gets the
job done. So when you go to compose a message to someone you might
want to use <command>comp -editor /usr/bin/vi/</> or <command>comp
-editor /usr/local/bin/pico/</> instead. Once you have run
<emphasis>comp</emphasis> you are in your editor and you see
something that looks like this:
<informalexample>
<screen>To:
cc:
Subject:
--------
</screen>
</informalexample></para>
<para>You need to put the person you are sending the mail to after the
<literal>To:</> line. It works the same way for the other headers
also, so you would need to put your subject after the
<literal>Subject:</> line. Then you would just put the body of your
message after the dashed lines. It may seem a bit simplistic since a
lot of email programs have special requesters that ask you for this
information but there really isn't any point to that. Plus this
really gives you excellent flexibility.
<informalexample>
<screen>To:<userinput>freebsd-rave@freebsd.org</>
cc:
Subject:<userinput>And on the 8th day God created the FreeBSD core team</>
--------
<userinput>Wow this is an amazing operating system. Thanks!</></screen>
</informalexample>
You can now save this message and exit your editor. You will see the
<prompt>What now?</> prompt and you can type in
<userinput>send</> or <userinput>s</> and hit
<keycap>return</>. Then the freebsd core team will receive their just
rewards. As I mentioned earlier you can also use other commands, for
example <command>quit</> if you don't want to send the
message.</para>
<para>The <command>forw</> command is stunningly similar. The big
difference being that the message you are forwarding is automatically
included in the outgoing message. When you run <command>forw</> it
will forward your current message. You can always tell it to forward
something else by doing something like <command>forw 23</> and then
message number 23 will be put in your outgoing message instead of the
current message. Beyond those small differences <command>forw</>
functions exactly the same as <command>comp</>. You go through the
exact same message sending process.</para>
<para>The <command>repl</> command will reply to whatever your
current message is, unless you give it a different message to reply
to. <command>repl</> will do its best to go ahead and fill in some of
the email headers already. So you will notice that the
<literal>To:</> header already has the address of the recipient in
there. Also the <literal>Subject:</> line will already be filled in.
You then go about the normal message composition process and you are
done. One useful command line option to know here is the
<option>-cc</option> option. You can use <parameter>all</>,
<parameter>to</>, <parameter>cc</>, <parameter>me</> after the
<option>-cc</option> option to have <command>repl</> automatically
add the various addresses to the cc list in the message. You have
probably noticed that the original message isn't included. This is
because most MH setups are configured to do this from the
start.</para>
</sect1>
<sect1>
<title><filename>components</>, and <filename>replcomps</>&mdash;components files for <command>comp</> and <command>repl</></title>
<para>The <filename>components</> file is usually in
<filename>/usr/local/lib/mh</filename>. You can copy that file into
your MH Mail directory and edit to contain what you want it to
contain. It is a fairly basic file. You have various email headers at
the top, a dashed line and then nothing. The
<command>comp</command> command just copies this
<filename>components</> file and then edits it. You can add any
kind of valid RFC822 header you want. For instance you could have
something like this in your <filename>components</> file:
<informalexample>
<screen>To:
Fcc: out
Subject:
X-Mailer: MH 6.8.3
X-Home-Page: http://www.freebsd.org/
-------</screen>
</informalexample>
MH would then copy this components file and throw you into your
editor. The <filename>components</> file is fairly simple. If you
wanted to have a signature on those messages you would just put your
signature in that <filename>components</> file.</para>
<para>The <filename>replcomps</> file is a bit more complex. The default
<filename>replcomps</> looks like this:
<informalexample>
<screen>%(lit)%(formataddr %&lt;{reply-to}%?{from}%?{sender}%?{return-path}%&gt;)\
%&lt;(nonnull)%(void(width))%(putaddr To: )\n%&gt;\
%(lit)%(formataddr{to})%(formataddr{cc})%(formataddr(me))\
%&lt;(nonnull)%(void(width))%(putaddr cc: )\n%&gt;\
%&lt;{fcc}Fcc: %{fcc}\n%&gt;\
%&lt;{subject}Subject: Re: %{subject}\n%&gt;\
%&lt;{date}In-reply-to: Your message of "\
%&lt;(nodate{date})%{date}%|%(pretty{date})%&gt;."%&lt;{message-id}
%{message-id}%&gt;\n%&gt;\
--------
</screen>
</informalexample></para>
<para>It's in the same basic format as the <filename>components</> file but
it contains quite a few extra formatting codes. The
<literal>%(lit)</> command makes room for the address. The
<literal>%(formataddr</> is a function that returns a proper email
address. The next part is <literal>%&lt;</literal> which means if and
the <literal>{reply-to}</> means the reply-to field in the original
message. So that might be translated this way:
<informalexample>
<screen>%&lt;<emphasis remap=bf>if</emphasis> {reply-to} <emphasis remap=bf>the original message has a reply-to</emphasis>
then give that to formataddr, %? <emphasis remap=bf>else</emphasis> {from} <emphasis remap=bf>take the
from address</emphasis>, %? <emphasis remap=bf>else</emphasis> {sender} <emphasis remap=bf>take the sender address</emphasis>, %?
<emphasis remap=bf>else</emphasis> {return-path} <emphasis remap=bf>take the return-path from the original
message</emphasis>, %&gt; <emphasis remap=bf>endif</emphasis>.</screen>
</informalexample></para>
<para>As you can tell MH formatting can get rather involved. You can
probably decipher what most of the other functions and variables
mean. All of the information on writing these format strings is in the
MH-Format man page. The really nice thing is that once you have built
your customized <filename>replcomps</> file you won't need to touch it
again. No other email program really gives you the power and
flexibility that MH gives you.</para>
</sect1>
</chapter>
</book>

7
en/tutorials/multios/Makefile
View file

@ -1,7 +0,0 @@
# $Id: Makefile,v 1.4 1997-07-01 05:38:14 max Exp $
DOCS= multios.docb
INDEXLINK= multios.html
.include "../../web.mk"

682
en/tutorials/multios/multios.docb
View file

@ -1,682 +0,0 @@
<!-- $Id: multios.docb,v 1.4 1998-11-30 23:14:55 billf Exp $ -->
<!DOCTYPE BOOK PUBLIC "-//Davenport//DTD DocBook V3.0//EN">
<book>
<bookinfo>
<bookbiblio>
<title>Installing and Using FreeBSD With Other Operating Systems</title>
<authorgroup>
<author>
<firstname>Jay</firstname>
<surname>Richmond</surname>
<affiliation>
<address>
<email>jayrich@sysc.com</email>
</address>
</affiliation>
</author>
</authorgroup>
<pubdate>6 August 1996</pubdate>
<abstract><para>This document discusses how to make FreeBSD coexist
nicely with other popular operating systems such as Linux, MS-DOS,
OS/2, and Windows 95. Special thanks to: Annelise Anderson
<email>andrsn@stanford.edu</email>, Randall Hopper
<email>rhh@ct.picker.com</email>, and Jordan K. Hubbard
<email>jkh@time.cdrom.com</email></para></abstract>
</bookbiblio>
</bookinfo>
<chapter>
<title>Overview</title>
<para>Most people can't fit these operating systems together
comfortably without having a larger hard disk, so special
information on large EIDE drives is included. Because there are so
many combinations of possible operating systems and hard disk
configurations, the <xref linkend="ch5"> section may be of the most use
to you. It contains descriptions of specific working computer setups
that use multiple operating systems.</para>
<para>This document assumes that you have already made room on your
hard disk for an additional operating system. Any time you
repartition your hard drive, you run the risk of destroying the data
on the original partitions. However, if your hard drive is completely
occupied by DOS, you might find the FIPS utility (included on the
FreeBSD CD-ROM in the <filename>\TOOLS</filename> directory or via
<ulink URL="ftp://ftp.freebsd.org/pub/FreeBSD/tools">ftp</ulink>)
useful. It lets you repartition your hard disk without destroying the
data already on it. There is also a commercial program available
called Partition Magic, which lets you size and delete partitions
without consequence.</para>
</chapter>
<chapter id="ch2">
<title>Overview of Boot Managers</title>
<para>These are just brief descriptions of some of the different boot
managers you may encounter. Depending on your computer setup, you may
find it useful to use more than one of them on the same
system.</para>
<variablelist>
<varlistentry>
<term>Boot Easy</term>
<listitem>
<para>This is the default boot manager used with FreeBSD. It has the
ability to boot most anything, including BSD, OS/2 (HPFS), Windows 95
(FAT and FAT32), and Linux. Partitions are selected with the
function keys.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>OS/2 Boot Manager</term>
<listitem>
<para>This will boot FAT, HPFS, FFS (FreeBSD), and EXT2
(Linux). It will also boot FAT32 partitions. Partitions are
selected using arrow keys. The OS/2 Boot Manager is the only one to
use its own separate partition, unlike the others which use the
master boot record (MBR). Therefore, it must be installed below the
1024th cylinder to avoid booting problems. It can boot Linux using
LILO when it is part of the boot sector, not the MBR. Go to <ulink
URL="http://www.linuxresources.com/LDP/HOWTO/HOWTO-INDEX.html">Linux HOWTOs</ulink>
on the World Wide Web for more information on booting Linux with
OS/2's boot manager.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>OS-BS</term>
<listitem> <para>This is an alternative to Boot Easy. It gives you
more control over the booting process, with the ability to set the
default partition to boot and the booting timeout. The beta version
of this programs allows you to boot by selecting the OS with your
arrow keys. It is included on the FreeBSD CD in the
<filename>\TOOLS</filename> directory, and via <ulink
URL="ftp://ftp.freebsd.org/pub/FreeBSD/tools">ftp</ulink>.</para>
</listitem> </varlistentry>
<varlistentry>
<term>LILO, or LInux LOader</term>
<listitem>
<para>This is a limited boot manager. Will boot FreeBSD, though some
customization work is required in the LILO configuration file.</para>
</listitem>
</varlistentry>
</variablelist>
<note id="fat32"><title>About FAT32</title><para>FAT32 is the replacement to
the FAT filesystem included in Microsoft's OEM SR2 Beta release,
which is expected to utilitized on computers pre-loaded with Windows
95 towards the end of 1996. It converts the normal FAT file system
and allows you to use smaller cluster sizes for larger hard drives.
FAT32 also modifies the traditional FAT boot sector and allocation
table, making it incompatible with some boot managers.</para></note>
</chapter>
<chapter id="ch3">
<title>A Typical Installation</title>
<para>Let's say I have two large EIDE hard drives, and I want to
install FreeBSD, Linux, and Windows 95 on them.</para>
<para>Here's how I might do it using these hard disks:
<itemizedlist>
<listitem>
<para><filename>/dev/wd0</> (first physical hard disk)</para>
</listitem>
<listitem>
<para><filename>/dev/wd1</> (second hard disk)</para>
</listitem>
</itemizedlist>
</para>
<para>Both disks have 1416 cylinders.</para>
<procedure>
<step><para>I boot from a MS-DOS or Windows 95 boot disk that
contains the <filename>FDISK.EXE</> utility and make a small 50 meg
primary partition (35-40 for Windows 95, plus a little breathing
room) on the first disk. Also create a larger partition on the
second hard disk for my Windows applications and data.</para></step>
<step><para>I reboot and install Windows 95 (easier said than done)
on the <filename>C:</> partition.</para> </step>
<step><para>The next thing I do is install Linux. I'm not sure about
all the distributions of Linux, but slackware includes LILO (see
<xref linkend="ch2">). When I am partitioning out my hard disk with
Linux <command>fdisk</command>, I would put all of Linux on the first
drive (maybe 300 megs for a nice root partition and some swap
space).</para></step>
<step><para>After I install Linux, and are prompted about installing
LILO, make SURE that I install it on the boot sector of my root
Linux partition, not in the MBR (master boot record).</para></step>
<step><para>The remaining hard disk space can go to FreeBSD. I also
make sure that my FreeBSD root slice does not go beyond the 1024th
cylinder. (The 1024th cylinder is 528 megs into the disk with our
hypothetical 720MB disks). I will use the rest of the hard drive
(about 270 megs) for the <filename>/usr</> and <filename>/</> slices
if I wish. The rest of the second hard disk (size depends on the
amount of my Windows application/data partition that I created in
step 1 can go to the <filename>/usr/src</> slice and swap
space.</para></step>
<step><para>When viewed with the Windows 95 <command>fdisk</> utility, my hard drives
should now look something like this:
<screen>
---------------------------------------------------------------------
Display Partition Information
Current fixed disk drive: 1
Partition Status Type Volume_Label Mbytes System Usage
C: 1 A PRI DOS 50 FAT** 7%
2 A Non-DOS (Linux) 300 43%
Total disk space is 696 Mbytes (1 Mbyte = 1048576 bytes)
Press Esc to continue
---------------------------------------------------------------------
Display Partition Information
Current fixed disk drive: 2
Partition Status Type Volume_Label Mbytes System Usage
D: 1 A PRI DOS 420 FAT** 60%
Total disk space is 696 Mbytes (1 Mbyte = 1048576 bytes)
Press Esc to continue
---------------------------------------------------------------------
</screen>
** May say FAT16 or FAT32 if you are using the OEM SR2 update.
See <xref linkend="ch2">).</para></step>
<step><para>Install FreeBSD. I make sure to boot with my first hard
disk set at <quote>NORMAL</> in the BIOS. If it is not, I'll have
the enter my true disk geometry at boot time (to get this, boot
Windows 95 and consult Microsoft Diagnostics (<filename>MSD.EXE</>),
or check your BIOS) with the parameter <literal>hd0=1416,16,63</>
where <replaceable>1416</> is the number of cylinders on my hard
disk, <replaceable>16</> is the number of heads per track, and
<replaceable>63</> is the number of sectors per track on the
drive.</para></step>
<step><para>When partitioning out the hard disk, I make sure to install
Boot Easy on the first disk. I don't worry about the second disk,
nothing is booting off of it.</para></step>
<step><para>When I reboot, Boot Easy should recognize my three
bootable partitions as DOS (Windows 95), Linux, and BSD
(FreeBSD).</para></step>
</procedure>
</chapter>
<chapter id="ch4">
<title>Special Considerations</title>
<para>Most operating systems are very picky about where and how they are
placed on the hard disk. Windows 95 and DOS need to be on the first
primary partitiin on the first hard disk. OS/2 is the exception. It
can be installed on the first or second disk in a primary or extended
partition. If you are not sure, keep the beginning of the bootable
partitions below the 1024th cylinder.</para>
<para>If you install Windows 95 on an existing BSD system, it will
<quote>destroy</> the MBR, and you will have to reinstall your
previous boot manager. Boot Easy can be reinstalled by using the
BOOTINST.EXE utility included in the \TOOLS directory on the CD-ROM,
and via <ulink
URL="ftp://ftp.freebsd.org/pub/FreeBSD/tools">ftp</ulink>. You can
also re-start the installation process and go to the partition
editor. From there, mark the FreeBSD partition as bootable,
select Boot Manager, and then type W to (W)rite out the information
to the MBR. You can now reboot, and Boot Easy should then
recognize Windows 95 as DOS.</para>
<para>Please keep in mind that OS/2 can read FAT and HPFS partitions,
but not FFS (FreeBSD) or EXT2 (Linux) partitions. Likewise, Windows
95 can only read and write to FAT and FAT32 (see <xref
linkend="ch2">) partitions. FreeBSD can read most file systems, but
currently cannot read HPFS partitions. Linux can read HPFS
partitions, but can't write to them. Recent versions of the Linux
kernel (2.x) can read and write to Windows 95 VFAT partitions (VFAT
is what gives Windows 95 long file names - it's pretty much the same
as FAT). Linux can read and write to most file systems. Got that?
I hope so.</para>
</chapter>
<chapter id="ch5">
<title>Examples</title>
<para><emphasis>(section needs work, please send your example to
<email>jayrich@sysc.com</email>)</emphasis>.</para>
<para>FreeBSD+Win95: If you installed FreeBSD after Windows 95, you
should see <literal>DOS</> on the Boot Easy menu. This is Windows
95. If you installed Windows 95 after FreeBSD, read <xref
linkend="ch4"> above. As long as your hard disk does not have 1024
cylinders you should not have a problem booting. If one of your
partitions goes beyond the 1024th cylinder however, and you get
messages like <errorname>invalid system disk</> under DOS (Windows 95)
and FreeBSD will not boot, try looking for a setting in your BIOS
called <quote>&gt; 1024 cylinder support</> or <quote>NORMAL/LBA</>
mode. DOS may need LBA (Logical Block Addressing) in order to boot
correctly. If the idea of switching BIOS settings every time you
boot up doesn't appeal to you, you can boot FreeBSD through DOS via
the <filename>FBSDBOOT.EXE</> utility on the CD (It should find your
FreeBSD partition and boot it.)</para>
<para>FreeBSD+OS/2+Win95: Nothing new here. OS/2's boot manger
can boot all of these operating systems, so that shouldn't be a
problem.</para>
<para>FreeBSD+Linux: You can also use Boot Easy to boot both operating
systems.</para>
<para>FreeBSD+Linux+Win95: (see <xref linkend="ch3">)</para>
</chapter>
<chapter id="sources">
<title>Other Sources of Help</title>
<para>There are many <ulink
URL="http://www.linuxresources.com/LDP/HOWTO/HOWTO-INDEX.html">Linux HOW-TOs</ulink> that
deal with multiple operating systems on the same hard disk.</para>
<para>The <ulink
URL="http://www.linuxresources.com/LDP/HOWTO/mini/Linux+DOS+Win95+OS2.html">Linux+DOS+Win95+OS2
mini-HOWTO</ulink> offers help on configuring the OS/2 boot manager, and the
<ulink
URL="http://www.linuxresources.com/LDP/HOWTO/mini/Linux+FreeBSD.html">Linux+FreeBSD
mini-HOWTO</ulink> might be interesting as well. The <ulink
URL="http://www.in.net/~jkatz/win95/Linux-HOWTO.html">Linux-HOWTO</ulink> is
also helpful.</para>
<para>The <ulink
URL="http://www.dorsai.org/~dcl/publications/NTLDR_Hacking">NT Loader
Hacking Guide</ulink> provides good information on multibooting
Windows NT, '95, and DOS with other operating systems.</para>
<para>And Hale Landis's "How It Works" document pack contains some good info
on all sorts of disk geometry and booting related topics. Here are a few
links that might help you find it: <ulink URL="ftp://fission.dt.wdc.com/pub/otherdocs/pc_systems/how_it_works/allhiw.zip">ftp://fission.dt.wdc.com/pub/otherdocs/pc_systems/how_it_works/allhiw.zip</ulink>,
<ulink URL="http://web.idirect.com/~frank/">http://www.cs.yorku.ca/People/frank/docs/</ulink>.</para>
<para>Finally, don't overlook FreeBSD's kernel documentation on the booting
procedure, available in the kernel source distribution (it unpacks to
<ulink URL="file:/usr/src/sys/i386/boot/biosboot/README.386BSD">file:/usr/src/sys/i386/boot/biosboot/README.386BSD</ulink>.</para>
</chapter>
<chapter>
<title>Technical Details</title>
<para><emphasis>(Contributed by Randall Hopper,
<email>rhh@ct.picker.com</email>)</emphasis></para>
<para>This section attempts to give you enough basic information
about your hard disks and the disk booting process so that you can
troubleshoot most problems you might encounter when getting set up to
boot several operating systems. It starts in pretty basic terms, so
you may want to skim down in this section until it begins to look
unfamiliar and then start reading.</para>
<sect1>
<title>Disk Primer</title>
<para>Three fundamental terms are used to describe the location of
data on your hard disk: Cylinders, Heads, and Sectors. It's not
particularly important to know what these terms relate to except to
know that, together, they identify where data is physically on your
disk.</para>
<para>Your disk has a particular number of cylinders, number of
heads, and number of sectors per cylinder-head (a cylinder-head also
known nown as a track). Collectively this information defines the
"physical disk geometry" for your hard disk. There are typically 512
bytes per sector, and 63 sectors per track, with the number of
cylinders and heads varying widely from disk to disk. Thus you can
figure the number of bytes of data that'll fit on your own disk by
calculating: <informalexample><para>(# of cylinders) &times; (#
heads) &times; (63 sectors/track) &times; (512
bytes/sect)</></informalexample> For example, on my 1.6 Gig Western
Digital AC31600 EIDE hard disk,that's: <informalexample><para>(3148
cyl) &times; (16 heads) &times; (63 sectors/track) &times (512
bytes/sect)</para></informalexample></para>
<para>which is 1,624,670,208 bytes, or around 1.6 Gig.</para>
<para>You can find out the physical disk geometry (number of
cylinders, heads, and sectors/track counts) for your hard disks using
ATAID or other programs off the net. Your hard disk probably came
with this information as well. Be careful though: if you're using
BIOS LBA (see <xref linkend="limits">), you can't use just any
program to get the physical geometry. This is because many programs
(e.g. <filename>MSD.EXE</> or FreeBSD fdisk) don't identify the
physical disk geometry; they instead report the
<firstterm>translated geometry</> (virtual numbers from using LBA).
Stay tuned for what that means.</para>
<para>One other useful thing about these terms. Given 3
numbers&mdash;a cylinder number, a head number, and a
sector-within-track number&mdash;you identify a specific absolute
sector (a 512 byte block of data) on your disk. Cylinders and Heads
are numbered up from 0, and Sectors are numbered up from 1.</para>
<para>For those that are interested in more technical details,
information on disk geometry, boot sectors, BIOSes, etc. can be found
all over the net. Query Lycos, Yahoo, etc. for <literal>boot
sector</> or <literal>master boot record</>. Among the useful info
you'll find are Hale Landis's <citetitle>How It Works</> document
pack. See the <xref linkend="sources"> section for a few pointers to
this pack.</para>
<para>Ok, enough terminology. We're talking about booting
here.</para>
</sect1>
<sect1 id="booting">
<title>The Booting Process</title>
<para>On the first sector of your disk (Cyl 0, Head 0, Sector 1)
lives the Master Boot Record (MBR). It contains a map of your disk.
It identifies up to 4 <firstterm>partitions</>, each of which is a
contiguous chunk of that disk. FreeBSD calls partitions
<firstterm>slices</> to avoid confusion with it's own partitions, but
we won't do that here. Each partition can contain its own operating
system.</para>
<para>Each partition entry in the MBR has a <firstterm>Partition
ID</>, a <firstterm>Start Cylinder/Head/Sector</>, and an
<firstterm>End Cylinder/Head/Sector</>. The Partition ID tells what
type of partition it is (what OS) and the Start/End tells where it
is. <xref linkend="tbl-pid"> lists a smattering of some common
Partition IDs.</para>
<table id="tbl-pid">
<title>Partition IDs</>
<tgroup cols="2">
<thead>
<row>
<entry>ID (hex)</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>01</entry>
<entry>Primary DOS12 (12-bit FAT)</entry>
</row>
<row>
<entry>04</entry>
<entry>Primary DOS16 (16-bit FAT)</entry>
</row>
<row>
<entry>05</entry>
<entry>Extended DOS</entry>
</row>
<row>
<entry>06</entry>
<entry>Primary big DOS (&gt; 32MB)</entry>
</row>
<row>
<entry>0A</entry>
<entry>OS/2</entry>
</row>
<row>
<entry>83</entry>
<entry>Linux (EXT2FS)</entry>
</row>
<row>
<entry>A5</entry>
<entry>FreeBSD, NetBSD, 386BSD (UFS)</entry>
</row>
</tbody>
</tgroup>
</table>
<para>Note that not all partitions are bootable (e.g. Extended DOS).
Some are&mdash;some aren't. What makes a partition bootable is the
configuration of the <firstterm>Partition Boot Sector</> that exists
at the beginning of each partition.</para>
<para>When you configure your favorite boot manager, it looks up the entries
in the MBR partition tables of all your hard disks and lets you name the
entries in that list. Then when you boot, the boot manager is invoked by
special code in the Master Boot Sector of the first probed hard disk on
your system. It looks at the MBR partition table entry corresponding to
the partition choice you made, uses the Start Cylinder/Head/Sector
information for that partition, loads up the Partition Boot Sector for that
partition, and gives it control. That Boot Sector for the partition itself
contains enough information to start loading the operating system on that
partition.</para>
<para>One thing we just brushed past that's important to know. All of your
hard disks have MBRs. However, the one that's important is the one on the
disk that's first probed by the BIOS. If you have only IDE hard disks, its
the first IDE disk (e.g. primary disk on first controller). Similarly for
SCSI only systems. If you have both IDE and SCSI hard disks though, the
IDE disk is typically probed first by the BIOS, so the first IDE disk is
the first probed disk. The boot manager you will install will be hooked into
the MBR on this first probed hard disk that we've just described.</para>
</sect1>
<sect1 id="limits">
<title>Booting Limitations and Warnings</title>
<para>Now the interesting stuff that you need to watch out for.</para>
<sect2>
<title>The dreaded 1024 cylinder limit and how BIOS LBA helps</title>
<para>The first part of the booting process is all done through the
BIOS, (if that's a new term to you, the BIOS is a software chip on
your system motherboard which provides startup code for your
computer). As such, this first part of the process is subject to the
limitations of the BIOS interface.</para>
<para>The BIOS interface used to read the hard disk during this period
(INT 13H, Subfunction 2) allocates 10 bits to the Cylinder Number, 8
bits to the Head Number, and 6 bits to the Sector Number. This
restricts users of this interface (i.e. boot managers hooked into
your disk's MBR as well as OS loaders hooked into the Boot Sectors)
to the following limits:
<itemizedlist>
<listitem><para>1024 cylinders, max</para></listitem>
<listitem><para>256 heads , max</para></listitem>
<listitem><para>64 sectors/track, max (actually 63, <literal>0</> isn't
available)</para></listitem>
</itemizedlist>
</para>
<para>Now big hard disks have lots of cylinders but not a lot of
heads, so invariably with big hard disks the number of cylinders is
greater than 1024. Given this and the BIOS interface as is, you
can't boot off just anywhere on your hard disk. The boot code (the
boot manager and the OS loader hooked into all bootable partitions'
Boot Sectors) has to reside below cylinder 1024. In fact, if your
hard disk is typical and has 16 heads, this equates to:
<informalexample>
<para>1024 cyl/disk &times; 16 heads/disk &times; 63 sect/(cyl-head)
&times; 512 bytes/sector</para>
</informalexample>
</para>
<para>which is around the often-mentioned 528MB limit.</para>
<para>This is where BIOS LBA (Logical Block Addressing) comes in. BIOS LBA
gives the user of the BIOS API calls access to physical cylinders above
1024 though the BIOS interfaces by redefining a cylinder. That is, it
remaps your cylinders and heads, making it appear through the BIOS as
though the disk has fewer cylinders and more heads than it actually
does. In other words, it takes advantage of the fact that hard disks have
relatively few heads and lots of cylinders by shifting the balance between
number of cylinders and number of heads so that both numbers lie below the
above-mentioned limits (1024 cylinders, 256 heads).</para>
<para>With BIOS LBA, the hard disk size limitation is virtually
removed (well, pushed up to 8 Gigabytes anyway). If you have an LBA
BIOS, you can put FreeBSD or any OS anywhere you want and not hit the
1024 cylinder limit.</para>
<para>To use my 1.6 Gig Western Digital as an example again, it's
physical geometry is:
<informalexample>
<para>(3148 cyl, 16 heads, 63 sectors/track, 512 bytes/sector)</para>
</informalexample>
</para>
<para>However, my BIOS LBA remaps this to:
<informalexample>
<para>( 787 cyl, 64 heads, 63 sectors/track, 512 bytes/sector)</para>
</informalexample>
</para>
<para>giving the same effective size disk, but with cylinder and head
counts within the BIOS API's range (Incidentally, I have both Linux and
FreeBSD existing on one of my hard disks above the 1024th physical
cylinder, and both operating systems boot fine, thanks to BIOS LBA).</para>
</sect2>
<sect2>
<title>Boot Managers and Disk Allocation</title>
<para>Another gotcha to watch out when installing boot managers is
allocating space for your boot manager. It's best to be aware of
this issue up front to save yourself from having to reinstall one or
more of your OSs.</para>
<para>If you followed the discussion in <xref linkend="booting">
about the Master Boot Sector (where the MBR is), Partition Boot
Sectors, and the booting process, you may have been wondering just
exactly where on your hard disk that nifty boot manager is going to
live. Well, some boot managers are small enough to fit entirely
within the Master Boot Sector (Cylinder 0, Head 0, Sector 0) along
with the partition table. Others need a bit more room and actually
extend a few sectors past the Master Boot Sector in the Cylinder 0
Head 0 track, since that's typically free&hellip;typically.</para>
<para>That's the catch. Some operating systems (FreeBSD included) let
you start their partitions right after the Master Boot Sector at
Cylinder 0, Head 0, Sector 2 if you want. In fact, if you give
FreeBSD's sysinstall a disk with an empty chunk up front or the whole
disk empty, that's where it'll start the FreeBSD partition by default
(at least it did when I fell into this trap). Then when you go to
install your boot manager, if it's one that occupies a few extra
sectors after the MBR, it'll overwrite the front of the first
partition's data. In the case of FreeBSD, this overwrites the
disk label, and renders your FreeBSD partition unbootable.</para>
<para>The easy way to avoid this problem (and leave yourself the
flexibility to try different boot managers later) is just to always
leave the first full track on your disk unallocated when you
partition your disk. That is, leave the space from Cylinder 0, Head
0, Sector 2 through Cylinder 0, Head 0, Sector 63 unallocated, and
start your first partition at Cylinder 0, Head 1, Sector 1.
For what it's worth, when you create a DOS partition at the
front of your disk, DOS leaves this space open by default (this is
why some boot managers assume it's free). So creating a DOS
partition up at the front of your disk avoids this problem
altogether. I like to do this myself, creating 1 Meg DOS partition
up front, because it also avoids my primary DOS drive letters
shifting later when I repartition.</para>
<para>For reference, the following boot managers use the
Master Boot Sector to store their code and data:
<itemizedlist>
<listitem>
<para>OS-BS 1.35</para>
</listitem>
<listitem>
<para>Boot Easy</para>
</listitem>
<listitem>
<para>LILO</para>
</listitem>
</itemizedlist>
</para>
<para>These boot managers use a few additional sectors after the
Master Boot Sector:
<itemizedlist>
<listitem>
<para>OS-BS 2.0 Beta 8 (sectors 2-5)</para>
</listitem>
<listitem>
<para>OS/2's boot manager</para>
</listitem>
</itemizedlist>
</para>
</sect2>
<sect2>
<title>What if your machine won't boot?</title>
<para>At some point when installing boot managers, you might leave the
MBR in a state such that your machine won't boot. This is unlikely,
but possible when re-FDISKing underneath an already-installed boot
manager.</para>
<para>If you have a bootable DOS partition on your disk, you can boot
off a DOS floppy, and run:
<informalexample>
<screen>A:\> <userinput>FDISK /MBR</></screen>
</informalexample>
</para>
<para>to put the original, simple DOS boot code back into the system. You can
then boot DOS (and DOS only) off the hard drive. Alternatively, just
re-run your boot manager installation program off a bootable floppy.</para>
</sect2>
</sect1>
</chapter>
</book>

7
en/tutorials/newuser/Makefile
View file

@ -1,7 +0,0 @@
# $Id: Makefile,v 1.3 1997-07-01 05:38:15 max Exp $
DOCS= newuser.docb
INDEXLINK= newuser.html
.include "../../web.mk"

943
en/tutorials/newuser/newuser.docb
View file

@ -1,943 +0,0 @@
<!-- $Id: newuser.docb,v 1.5 1998-08-09 22:53:56 wosch Exp $ -->
<!-- The FreeBSD Documentation Project -->
<!DOCTYPE BOOK PUBLIC "-//Davenport//DTD DocBook V3.0//EN">
<book>
<bookinfo>
<bookbiblio>
<title>For People New to Both FreeBSD and Unix</title>
<authorgroup>
<author>
<firstname>Annelise</firstname>
<surname>Anderson</surname>
<affiliation>
<address><email>andrsn@andrsn.stanford.edu</email></address>
</affiliation>
</author>
</authorgroup>
<pubdate>August 15, 1997</pubdate>
<abstract><para>Congratulations on installing FreeBSD! This
introduction is for people new to both FreeBSD
<emphasis>and</emphasis> Un*x&mdash;so it starts with basics. It
assumes you're using version 2.0.5 or later of FreeBSD as distributed
by Walnut Creek or FreeBSD.ORG, your system (for now) has a single
user (you)&mdash;and you're probably pretty good with DOS/Windows or
OS/2.</para></abstract>
</bookbiblio>
</bookinfo>
<chapter>
<title>Logging in and Getting Out</title>
<para>Log in (when you see <systemitem
class=prompt>login:</systemitem>) as a user you created during
installation or as <firstterm>root</firstterm>. (Your FreeBSD
installation will already have an account for root; root can go
anywhere and do anything, including deleting essential files, so be
careful!) The symbols % and # in the following stand for the prompt
(yours may be different), with % indicating an ordinary user and
# indicating root. </para>
<para>To log out (and get a new <systemitem class=prompt>login:</systemitem> prompt) type
<informalexample>
<screen># <userinput>exit</userinput></screen>
</informalexample>
as often as necessary. Yes, press <keysym>enter</keysym> after
commands, and remember that Unix is
case-sensitive&mdash;<command>exit</command>, not
<command>EXIT</command>.</para>
<para>To shut down the machine type:
<informalexample>
<screen># <userinput>/sbin/shutdown -h now</userinput></screen>
</informalexample>
Or to reboot type
<informalexample>
<screen># <userinput>/sbin/shutdown -r now</userinput></screen>
</informalexample>
or
<informalexample>
<screen># <userinput>/sbin/reboot</userinput></screen>
</informalexample>
</para>
<para>You can also reboot with
<keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>Delete</keycap></keycombo>.
Give it a little time to do its work. This is equivalent to
<command>/sbin/reboot</command> in recent releases of FreeBSD, and is
much, much better than hitting the reset button. You don't want to
have to reinstall this thing, do you?</para>
</chapter>
<chapter>
<title>Adding A User with Root Privileges</title>
<para>If you didn't create any users when you installed the system and
are thus logged in as root, you should probably create a user now with
<informalexample>
<screen># <userinput>adduser</userinput></screen>
</informalexample>
The first time you use adduser, it might ask for some defaults to save. You
might want to make the default shell csh instead of sh, if it suggests
sh as the default. Otherwise just press enter to accept each default.
These defaults are saved in <filename>/etc/adduser.conf</filename>,
an editable file.</para>
<para>Suppose you create a user <emphasis>jack</emphasis> with
full name <emphasis>Jack Benimble</emphasis>. Give jack a password
if security (even kids around who might pound on the keyboard) is an
issue. When it asks you if you want to invite jack into other
groups, type <userinput>wheel</userinput>
<informalexample>
<screen>Login group is ``jack''. Invite jack into other groups: <userinput>wheel</userinput></screen>
</informalexample>
This will make it possible to log in as <emphasis>jack</emphasis> and
use the <command>su</command> command to become root. Then you won't
get scolded any more for logging in as root.</para>
<para>You can quit <command>adduser</command> any time by typing
<keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>, and at
the end you'll have a chance to approve your new user or simply type
<keycap>n</keycap> for no. You might want to create a
second new user (jill?) so that when you edit jack's login files,
you'll have a hot spare in case something goes wrong.</para>
<para>Once you've done this, use <command>exit</command>
to get back to a login prompt and log in as
<emphasis>jack</emphasis>. In general, it's a good idea to do as
much work as possible as an ordinary user who doesn't have the
power&mdash;and risk&mdash;of root.</para>
<para>If you already created a user and you want the user to be able
to <command>su</command> to root, you can log in as root
and edit the file <filename>/etc/group</filename>, adding jack to the
first line (the group wheel). But first you need to practice
<command>vi</command>, the text editor--or use the simpler text
editor, <command>ee</command>, installed on recent version of
FreeBSD.</para>
<para>To delete a user, use the <command>rmuser</command> command.</para>
</chapter>
<chapter>
<title>Looking Around</title>
<para>Logged in as an ordinary user, look around and try out some
commands that will access the sources of help and information within
FreeBSD.</para>
<para>Here are some commands and what they do:
<variablelist>
<varlistentry><term><command>id</command></term>
<listitem>
<para>Tells you who you are!</para>
</listitem>
</varlistentry>
<varlistentry><term><command>pwd</command></term>
<listitem>
<para>Shows you where you are&mdash;the current
working directory.</para>
</listitem>
</varlistentry>
<varlistentry><term><command>ls</command></term>
<listitem>
<para>Lists the files in the current directory.</para>
</listitem>
</varlistentry>
<varlistentry><term><command>ls <option>-F</option></command></term>
<listitem>
<para>Lists the files in the current directory with a
<literal>*</literal> after executables, a <literal>/</literal> after
directories, and an <literal>@</literal> after symbolic links.</para>
</listitem>
</varlistentry>
<varlistentry><term><command>ls <option>-l</option></command></term>
<listitem>
<para>Lists the files in long format&mdash;size,
date, permissions.</para>
</listitem>
</varlistentry>
<varlistentry><term><command>ls <option>-a</option></command></term>
<listitem>
<para>Lists hidden <quote>dot</quote>
files with the others. If you're root, the<quote>dot</quote> files
show up without the <option>-a</option> switch.</para>
</listitem>
</varlistentry>
<varlistentry><term><command>cd</command></term>
<listitem>
<para>Changes directories. <command>cd
<parameter>..</parameter></command> backs up one level; note the
space after <command>cd</command>. <command>cd
<parameter>/usr/local</parameter></command> goes there. <command>cd
<parameter>~</parameter></command> goes to the home directory of the
person logged in&mdash;e.g., <filename>/usr/home/jack</filename>.
Try <command>cd <parameter>/cdrom</parameter></command>, and then
<command>ls</command>, to find out if your CDROM is mounted and
working.</para>
</listitem>
</varlistentry>
<varlistentry><term><command>view <replaceable>filename</replaceable></command></term>
<listitem>
<para>Lets you look at a file (named
<replaceable>filename</replaceable> without changing it. Try
<command>view <parameter>/etc/fstab</parameter></command>.
<command>:q</command> to quit.</para>
</listitem>
</varlistentry>
<varlistentry><term><command>cat <replaceable>filename</replaceable></command></term>
<listitem>
<para>Displays <replaceable>filename</replaceable> on screen. If
it's too long and you can see only the end of it, press
<keycap>ScrollLock</keycap> and use the <keycap>up-arrow</keycap> to
move backward; you can use <keycap>ScrollLock</keycap> with man pages
too. Press <keycap>ScrollLock</keycap> again to quit scrolling. You
might want to try <command>cat</command> on some of the dot files in
your home directory&mdash;<command>cat
<parameter>.cshrc</parameter></command>, <command>cat
<parameter>.login</parameter></command>, <command>cat
<parameter>.profile</parameter></command>.</para>
</listitem>
</varlistentry>
</variablelist>
You'll notice aliases in <filename>.cshrc</filename> for some of the
<command>ls</command> commands (they're very convenient).
You can create other aliases by editing <filename>.cshrc</filename>.
You can make these aliases available to all users on the system by
putting them in the system-wide csh configuration file,
<filename>/etc/csh.cshrc</filename>.</para>
</chapter>
<chapter>
<title>Getting Help and Information</title>
<para>Here are some useful sources of help.
<replaceable>Text</replaceable> stands for something of your choice
that you type in&mdash;usually a command or filename.</para>
<variablelist>
<varlistentry><term><command>apropos <replaceable>text</replaceable></command></term>
<listitem>
<para>Everything containing string <replaceable>text</replaceable>
in the <database>whatis database</database>.</para>
</listitem>
</varlistentry>
<varlistentry><term><command>man <replaceable>text</replaceable></command></term>
<listitem>
<para>The man page for <replaceable>text</replaceable>. The major
source of documentation for Un*x systems. <command>man
<parameter>ls</parameter></command> will tell you all the ways to use
the <command>ls</command> command. Press <keycap>Enter</keycap> to
move through text,
<keycombo><keycap>Ctrl</keycap><keycap>b</keycap></keycombo> to go
back a page, <keycombo><keycap>Ctrl</keycap><keycap>f</keycap></keycombo> to
go forward, <keycap>q</keycap> or
<keycombo><keycap>Ctrl</keycap><keycap>c</keycap></keycombo> to
quit.</para>
</listitem>
</varlistentry>
<varlistentry><term><command>which <replaceable>text</replaceable></command></term>
<listitem>
<para>Tells you where in the user's path the command
<replaceable>text</replaceable> is found.</para>
</listitem>
</varlistentry>
<varlistentry><term><command>locate <replaceable>text</replaceable></command></term>
<listitem>
<para>All the paths where the string <replaceable>text</replaceable>
is found.</para>
</listitem>
</varlistentry>
<varlistentry><term><command>whatis <replaceable>text</replaceable></command></term>
<listitem>
<para>Tells you what the command <replaceable>text</replaceable>
does and its man page. Typing <command>whatis *</command> will tell
you about all the binaries in the current directory.</para>
</listitem>
</varlistentry>
<varlistentry><term><command>whereis <replaceable>text</replaceable></command></term>
<listitem>
<para>Finds the file <replaceable>text</replaceable>, giving its full
path.</para>
</listitem>
</varlistentry>
</variablelist>
<para>You might want to try using <command>whatis</command> on some
common useful commands like <command>cat</command>,
<command>more</command>, <command>grep</command>,
<command>mv</command>, <command>find</command>,
<command>tar</command>, <command>chmod</command>,
<command>chown</command>, <command>date</command>, and
<command>script</command>. <command>more</command> lets you read a
page at a time as it does in DOS, e.g., <command>ls -l |
more</command> or <command>more
<replaceable>filename</replaceable></command>. The
<literal>*</literal> works as a wildcard&mdash;e.g., <command>ls
w*</command> will show you files beginning with
<literal>w</literal>.</para>
<para>Are some of these not working very well? Both
<command>locate</command> and <command>whatis</command>
depend on a database that's rebuilt weekly. If your machine isn't
going to be left on over the weekend (and running FreeBSD), you might
want to run the commands for daily, weekly, and monthly maintenance
now and then. Run them as root and give each one time to finish
before you start the next one, for now.
<informalexample>
<screen># <userinput>/etc/daily</userinput>
<lineannotation>output omitted</lineannotation>
# <userinput>/etc/weekly</userinput>
<lineannotation>output omitted</lineannotation>
# <userinput>/etc/monthly</userinput>
<lineannotation>output omitted</lineannotation></screen>
</informalexample></para>
<para>If you get tired waiting, press
<keycombo><keycap>Alt</keycap><keycap>F2</keycap></keycombo> to get
another <firstterm>virtual console</firstterm>, and log in again.
After all, it's a multi-user, multi-tasking system. Nevertheless
these commands will probably flash messages on your screen while
they're running; you can type <command>clear</command> at the prompt
to clear the screen. Once they've run, you might want to look at
<filename>/var/mail/root</filename> and
<filename>/var/log/messages</filename>.</para>
<para>Basically running such commands is part of system
administration&mdash;and as a single user of a Unix system, you're
your own system administrator. Virtually everything you need to be
root to do is system administration. Such responsibilities aren't
covered very well even in those big fat books on Unix, which seem to
devote a lot of space to pulling down menus in windows managers. You
might want to get one of the two leading books on systems
administration, either Evi Nemeth et.al.'s <citetitle>UNIX System
Administration Handbook</citetitle> (Prentice-Hall, 1995, ISBN
0-13-15051-7)&mdash;the second edition with the red cover; or
&AElig;leen Frisch's <citetitle>Essential System
Administration</citetitle> (O'Reilly &amp; Associates, 1993, ISBN
0-937175-80-3). I used Nemeth.</para>
</chapter>
<chapter>
<title>Editing Text</title>
<para>To configure your system, you need to edit text files. Most of
them will be in the <filename>/etc</filename> directory; and you'll
need to <command>su</command> to root to be able to change them. You
can use the easy <command>ee</command>, but in the long run the
text editor <command>vi</command> is worth learning. There's an
excellent tutorial on vi in
<filename>/usr/src/contrib/nvi/docs/tutorial</filename> if you have
that installed; otherwise you can get it by ftp to
ftp.cdrom.com in the directory
FreeBSD/FreeBSD-current/src/contrib/nvi/docs/tutorial.</para>
<para>Before you edit a
file, you should probably back it up. Suppose you want to edit
<filename>/etc/rc.conf</filename>. You could just use <command>cd
/etc</command> to get to the <filename>/etc</filename> directory and
do:
<informalexample>
<screen># <userinput>cp rc.conf rc.conf.orig</userinput></screen>
</informalexample>
This would copy <filename>rc.conf</filename> to
<filename>rc.conf.orig</filename>, and you could later copy
<filename>rc.conf.orig</filename> to <emphasis
remap=tt>rc.conf</emphasis> to recover the original. But even
better would be moving (renaming) and then copying back:
<informalexample>
<screen># <userinput>mv rc.conf rc.conf.orig</userinput>
# <userinput>cp rc.conf.orig rc.conf</userinput></screen>
</informalexample>
because the <command>mv</command> command preserves the original date
and owner of the file. You can now edit
<filename>rc.conf</filename>. If you want the original back, you'd
then <userinput>mv rc.conf rc.conf.myedit</userinput>
(assuming you want to preserve your edited version) and then
<informalexample>
<screen># <userinput>mv rc.conf.orig rc.conf</userinput></screen>
</informalexample>
to put things back the way they were.</para>
<para>To edit a file, type
<informalexample>
<screen># <userinput>vi <replaceable>filename</replaceable></userinput></screen>
</informalexample>
Move through the text with the arrow keys. <keycap>Esc</keycap> (the
escape key) puts <command>vi</command> in command mode. Here are some
commands:
<variablelist>
<varlistentry><term><command>x</command></term>
<listitem>
<para>delete letter the cursor is on</para>
</listitem>
</varlistentry>
<varlistentry><term><command>dd</command></term>
<listitem>
<para>delete the entire line (even if it wraps on the screen)</para>
</listitem>
</varlistentry>
<varlistentry><term><command>i</command></term>
<listitem>
<para>insert text at the cursor</para>
</listitem>
</varlistentry>
<varlistentry><term><command>a</command></term>
<listitem>
<para>insert text after the cursor</para>
</listitem>
</varlistentry>
</variablelist>
Once you type <command>i</command> or <command>a</command>, you can enter text.
<command>Esc</command> puts you back in command mode where you can type
<variablelist>
<varlistentry><term><command>:w</command></term>
<listitem>
<para>to write your changes to disk and continue editing</para>
</listitem>
</varlistentry>
<varlistentry><term><command>:wq</command></term>
<listitem>
<para>to write and quit</para>
</listitem>
</varlistentry>
<varlistentry><term><command>:q!</command></term>
<listitem>
<para>to quit without saving changes</para>
</listitem>
</varlistentry>
<varlistentry><term><command>/<replaceable>text</replaceable></command></term>
<listitem>
<para>to move the cursor to <replaceable>text</replaceable>;
<command>/<keycap>Enter</keycap></command> (the enter key) to find
the next instance of <replaceable>text</replaceable>.</para>
</listitem>
</varlistentry>
<varlistentry><term><command>G</command></term>
<listitem>
<para>to go to the end of the file</para>
</listitem>
</varlistentry>
<varlistentry><term><command><replaceable>n</replaceable>G</command></term>
<listitem>
<para>to go to line <replaceable>n</replaceable> in
the file, where <replaceable>n</replaceable> is a number</para>
</listitem>
</varlistentry>
<varlistentry><term><keycombo><keycap>Ctrl</><keycap>L</></keycombo></term>
<listitem>
<para>to redraw the screen</para>
</listitem>
</varlistentry>
<varlistentry><term><keycombo><keycap>Ctrl</><keycap>b</></> and <keycombo><keycap>Ctrl</><keycap>f</></></term>
<listitem>
<para>go back
and forward a screen, as they
do with <command>more</> and <command>view</>.</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>Practice with <command>vi</> in your home directory by creating
a new file with <command>vi <replaceable>filename</></> and adding
and deleting text, saving the file, and calling it up again.
<command>vi</> delivers some surprises because it's really quite
complex, and sometimes you'll inadvertently issue a command that will
do something you don't expect. (Some people actually like
<command>vi</>&mdash;it's more powerful than DOS EDIT&mdash;find out
about the <command>:r</> command.) Use <keycap>Esc</> one or
more times to be sure you're in command mode and proceed from there
when it gives you trouble, save often with <command>:w</>, and
use <command>:q!</> to get out and start over (from
your last <command>:w</>) when you need to.</para>
<para>Now you can <command>cd</> to <filename>/etc</filename>,
<command>su</> to root, use <command>vi</> to edit the file
<filename>/etc/group</filename>, and add a user to wheel so the user
has root privileges. Just add a comma and the user's login name to
the end of the first line in the file, press <keycap>Esc</>, and use
<command>:wq</> to write the file to disk and quit. Instantly
effective. (You didn't put a space after the comma, did you?)</para>
</chapter>
<chapter>
<title>Printing Files from DOS</title>
<para>At this point you probably don't have the printer working, so here's a
way to create a file from a man page, move it to a floppy, and then
print it from DOS. Suppose you want to read carefully about changing
permissions on files (pretty important). You can use the command
man chmod to read about it. The command
<informalexample>
<screen># <userinput>man chmod | col -b &gt; chmod.txt</></screen>
</informalexample>
will remove formatting codes and send the man page to
the <filename>chmod.txt</filename> file
instead of showing it on your screen. Now put a dos-formatted
diskette in your floppy drive a, <command>su</> to
root, and type
<informalexample>
<screen># <userinput>/sbin/mount -t msdos /dev/fd0 /mnt</></screen>
</informalexample>
to mount the floppy drive on <filename>/mnt</filename>.</para>
<para>Now (you no longer need to be root, and you can type
<command>exit</> to get back to being user jack) you can go to the
directory where you created chmod.txt and copy the file to the floppy
with:
<informalexample>
<screen>% <userinput>cp chmod.txt /mnt</></screen>
</informalexample>
and use <command>ls /mnt</command> to get a directory listing of
<filename>/mnt</filename>, which should show the file
<filename>chmod.txt</filename>.</para>
<para>You might especially want to make a file from
<filename>/sbin/dmesg</filename> by typing
<informalexample>
<screen>% <userinput>/sbin/dmesg &gt; dmesg.txt</></screen>
</informalexample>
and copying <filename>dmesg.txt</filename> to the floppy.
<command>/sbin/dmesg</command> is the boot log record, and it's
useful to understand it because it shows what FreeBSD found when it
booted up. If you ask questions on
<email>freebsd-questions@FreeBSD.ORG</> or on a USENET
group&mdash;like <quote>FreeBSD isn't finding my tape drive, what do
I do?</quote>&mdash;people will want to know what <command>dmesg</>
has to say.</para>
<para>You can now dismount the floppy drive (as root) to get the disk
out with
<informalexample>
<screen># <userinput>/sbin/umount /mnt</></screen>
</informalexample>
and reboot to go to DOS. Copy these files to a DOS directory, call
them up with DOS EDIT, Windows Notepad or Wordpad, or a word processor, make a
minor change so the file has to be saved, and print as you normally
would from DOS or Windows. Hope it works! man pages come out best if
printed with the dos <command>print</> command. (Copying files from
FreeBSD to a mounted dos partition is in some cases still a little
risky.)</para>
<para>Getting the printer printing from FreeBSD involves creating an
appropriate entry in <filename>/etc/printcap</filename> and creating
a matching spool directory in
<filename>/var/spool/output</filename>. If your printer is on
<hardware>lpt0</> (what dos calls <hardware>LPT1</>), you may only
need to go to <filename>/var/spool/output</filename> and (as root)
create the directory <filename>lpd</> by typing:
<command>
mkdir lpd</command>, if it doesn't already
exist.
Then the printer should respond if it's turned on when the system is
booted, and lp or lpr should send a file to the printer. Whether or
not the file actually prints depends on configuring it, which is
covered in the <ulink
URL="../../handbook/handbook.html">FreeBSD
handbook.</></para>
</chapter>
<chapter>
<title>Other Useful Commands</title>
<para>
<variablelist>
<varlistentry><term><command>df</></term>
<listitem>
<para>shows file space and mounted systems.</para>
</listitem>
</varlistentry>
<varlistentry><term><command>ps aux</></term>
<listitem>
<para>shows processes running. <command>ps ax</> is a narrower form.</para>
</listitem>
</varlistentry>
<varlistentry><term><command>rm <replaceable>filename</></></term>
<listitem>
<para>remove <replaceable>filename</>.</para>
</listitem>
</varlistentry>
<varlistentry><term><command>rm -R <replaceable>dir</></></term>
<listitem>
<para>removes a directory <replaceable>dir</> and all
subdirectories&mdash;careful!</para>
</listitem>
</varlistentry>
<varlistentry><term><command>ls -R</command></term>
<listitem>
<para>lists files in the current
directory and all subdirectories;
I used a variant, <command>ls -AFR &gt; where.txt</command>,
to get a list of all
the files in <filename>/</filename> and (separately)
<filename>/usr</filename> before I found better
ways to find files.</para>
</listitem>
</varlistentry>
<varlistentry><term><command>passwd</></term>
<listitem>
<para>to change user's password (or root's password)</para>
</listitem>
</varlistentry>
<varlistentry><term><command>man hier</></term>
<listitem>
<para>man page on the Unix file system</para>
</listitem>
</varlistentry>
</variablelist></para>
<para>Use <command>find</> to locate filename in <filename>/usr</filename>
or any of its subdirectories with
<informalexample>
<screen>% <userinput>find /usr -name "<replaceable>filename</>"</></screen>
</informalexample>
You can use <literal>*</literal> as a wildcard in
<parameter>"<replaceable>filename</>"</> (which should be in
quotes). If you tell find to search in <filename>/</filename>
instead of <filename>/usr</filename> it will look for the file(s) on
all mounted file systems, including the CDROM and the dos
partition.</para>
<para>An excellent book that explains Unix commands and utilities is
Abrahams &amp; Larson, <citetitle>Unix for the Impatient</citetitle>
(2nd ed., Addison-Wesley, 1996). There's also a lot of Unix
information on the Internet. Try the <ulink
URL="http://www.eecs.nwu.edu/unix.html">Unix Reference
Desk</ulink>.</para>
</chapter>
<chapter>
<title>Next Steps</title>
<para>You should now have the tools you need to get around and edit
files, so you can get everything up and running. There is a great
deal of information in the FreeBSD handbook (which is probably on
your hard drive) and <ulink URL="http://www.freebsd.org/">FreeBSD's
web site</ulink>. A wide variety of packages and ports are on the
<ulink URL="http://www.cdrom.com/">Walnut Creek</ulink> CDROM as well
as the web site. The handbook tells you more about how to use them
(get the package if it exists, with <command>pkg_add
/cdrom/packages/All/<replaceable>packagename</></>,
where <replaceable>packagename</replaceable> is the filename of the
package). The cdrom has lists of the packages and ports with brief
descriptions in <filename>cdrom/packages/index</filename>,
<filename>cdrom/packages/index.txt</filename>, and
<filename>cdrom/ports/index</filename>, with fuller descriptions in
<filename>/cdrom/ports/*/*/pkg/DESCR</filename>, where the
<literal>*</literal>s represent subdirectories of kinds of programs
and program names respectively.</para>
<para>If you find the handbook too sophisticated (what with
<command>lndir</> and all) on installing ports from the cdrom,
here's what usually works:</para>
<para>Find the port you want, say <command>kermit</>. There will be
a directory for it on the cdrom. Copy the subdirectory to
<filename>/usr/local</filename> (a good place for software you add
that should be available to all users) with:
<informalexample>
<screen># <userinput>cp -R /cdrom/ports/comm/kermit /usr/local</></screen>
</informalexample>
This should result in a <filename>/usr/local/kermit</filename>
subdirectory that has all the files that the
<command>kermit</command> subdirectory on the CDROM has.</para>
<para>Next, create the directory <filename>/usr/ports/distfiles</filename>
if it doesn't already exist using <command>mkdir</>. Now check
check <filename>/cdrom/ports/distfiles</filename> for a
file with a name that indicates it's the port you want. Copy that
file to <filename>/usr/ports/distfiles</filename>; in recent versions
you can skip this step, as FreeBSD will do it for you.
In the case of <command>kermit</>, there is no
distfile.</para>
<para>Then <command>cd</> to the subdirectory of
<filename>/usr/local/kermit</filename> that has the file
<filename>Makefile</>. Type
<informalexample>
<screen># <userinput>make all install</></screen>
</informalexample>
</para>
<para>During this process the port will ftp to get any compressed
files it needs that it didn't find on the cdrom or in
<filename>/usr/ports/distfiles</filename>. If you don't have your
network running yet and there was no file for the port in
<filename>/cdrom/ports/distfiles</filename>, you will have to get
the distfile using another machine and copy it to
<filename>/usr/ports/distfiles</filename> from a floppy or your dos
partition. Read <filename>Makefile</> (with <command>cat</> or
<command>more</> or <command>view</>) to find out where to go (the
master distribution site) to get the file and what its name is. Its
name will be truncated when downloaded to DOS, and after you get it
into <filename>/usr/ports/distfiles</filename> you'll have to rename
it (with the <command>mv</> command) to its original name so it can
be found. (Use binary file transfers!) Then go back to
<filename>/usr/local/kermit</filename>, find the directory with
<filename>Makefile</>, and type <command>make all install</>.</para>
<para>The other thing that happens when installing ports or packages
is that some other program is needed. If the installation stops with
a message <errorname>can't find unzip</errorname> or whatever, you
might need to install the package or port for unzip before you
continue.</para>
<para>Once it's installed type <command>rehash</> to make FreeBSD
reread the files in the path so it knows what's there. (If you get a
lot of <errorname>path not found</> messages when you use
<command>whereis</> or which, you might want to make additions to the
list of directories in the path statement in
<filename>.cshrc</filename> in your home directory. The path
statement in Unix does the same kind of work it does in DOS, except
the current directory is not (by default) in the path for security
reasons; if the command you want is in the directory you're in, you
need to type <filename>./</filename> before the command to make it
work; no space after the slash.)</para>
<para>You might want to get the most recent version of Netscape from
their <ulink URL="ftp://ftp.netscape.com">ftp site</ulink>. (Netscape
requires the X Window System.) There's now a FreeBSD version, so look
around carefully. Just use <command>gunzip
<replaceable>filename</></> and <command>tar xvf
<replaceable>filename</></> on it, move the binary to
<filename>/usr/local/bin</filename> or some other place binaries are
kept, <command>rehash</>, and then put the following lines in
<filename>.cshrc</filename> in each user's home directory or (easier)
in <filename>/etc/csh.cshrc</filename>, the system-wide csh start-up
file:
<informalexample>
<programlisting>setenv XKEYSYMDB /usr/X11R6/lib/X11/XKeysymDB
setenv XNLSPATH /usr/X11R6/lib/X11/nls</>
</informalexample>
This assumes that the file <filename>XKeysymDB</> and the directory
<filename>nls</> are in <filename>/usr/X11R6/lib/X11</filename>; if
they're not, find them and put them there.</para>
<para>If you originally got Netscape as a port using the CDROM (or
ftp), don't replace <filename>/usr/local/bin/netscape</filename> with
the new netscape binary; this is just a shell script that sets up the
environmental variables for you. Instead rename the new binary to
<filename>netscape.bin</filename> and replace the old binary, which
is <filename>/usr/local/lib/netscape/netscape.bin</filename>.</para>
</chapter>
<chapter>
<title>Your Working Environment</title>
<para>Your shell is the most important part of your working environment.
In DOS, the usual shell is command.com. The shell is what interprets
the commands you type on the command line, and thus communicates with
the rest of the operating system. You can also write shell
scripts, which are like DOS batch files: a series of commands to be
run without your intervention.</para>
<para>Two shells come installed with FreeBSD: csh and sh. csh is good for
command-line work, but scripts should be written with sh (or bash). You can
find out what shell you have by typing <command>echo $SHELL</command>.</para>
<para>The csh shell is okay, but tcsh does everything csh does and more. It
It allows you to recall commands with the arrow keys and edit them.
It has tab-key completion
of filenames (csh uses the escape key), and it lets you switch to the
directory you were last in with <command>cd -</command>. It's also much
easier to alter your prompt with tcsh. It makes life a lot easier.</para>
<para>Here are the three steps for installing a new shell:</para>
<para> 1. Install the shell as a port or a package, just as you
would any other port or package. Use <command>rehash</command> and
<command>which tcsh</command> (assuming you're installing tcsh) to
make sure it got installed.</para>
<para> 2. As root, edit <filename>/etc/shells</filename>, adding
a line in the file for the new shell, in this case /usr/local/bin/tcsh,
and save the file. (Some ports may do this for you.)</para>
<para> 3. Use the <command>chsh</command> command to change your shell to
tcsh permanently, or type <command>tcsh</command> at the prompt to
change your shell without logging in again.</para>
<para><emphasis>Note: It can be dangerous to change root's shell</emphasis>
to something other than sh or csh on early versions of FreeBSD and many
other versions of Unix; you may not have a working shell when the system
puts you into single user mode. The solution is to use <command>su -m</command>
to become root, which will give you the tcsh as root, because the shell is part
of the environment. You can make this permanent by adding it to your
<filename>.tcshrc</filename> file as an alias with <programlisting>alias su su -m.</></para>
<para>When tcsh starts up, it will read the
<filename>/etc/csh.cshrc</filename> and <filename>/etc/csh.login</filename>
files, as does csh. It will also read the
<filename>.login</filename> file in your home directory and the
<filename>.cshrc</filename>
file as well, unless you provide a <filename>.tcshrc</filename>
file. This you can do by simply copying <filename>.cshrc</filename>
to <filename>.tcshrc</filename>.</para>
<para>Now that you've installed tcsh, you can adjust your prompt. You can
find the details in the manual page for tcsh, but here is a line to
put in your <filename>.tcshrc</filename> that will tell you how many
commands you have typed, what time it is, and what directory you are in.
It also produces a <literal>></literal> if you're an ordinary user and
a <literal>#</literal> if you're root, but tsch will do that in any
case:</para>
<para>
set prompt = "%h %t %~ %# "</para>
<para>This should go in the same place as the existing set prompt line
if there is one, or under "if($?prompt) then" if not.
Comment out the old line; you can always switch back to it if you prefer
it. Don't forget the spaces and quotes. You can get the <filename>.tcshrc</filename> reread by typing <command>source .tcshrc</command>.</para>
<para>You can get a listing of other environmental variables that
have been set by typing <command>env</command> at the prompt. The
result will show you your default editor, pager, and terminal type,
among possibly many others. A useful command if you log in from a
remote location and can't run a program because the terminal isn't
capable is
<command>setenv TERM vt100</command>.</para>
</chapter>
<chapter>
<title>Other</title>
<para>As root, you can dismount the CDROM with <command>/sbin/umount
/cdrom</>, take it out of the drive, insert another one, and mount it
with <command>/sbin/mount_cd9660 /dev/cd0a /cdrom</> assuming
<hardware>cd0a</> is the device name for your CDROM drive. The
most recent versions of FreeBSD let you mount the cdrom with just
<command>/sbin/mount /cdrom</command>.</para>
<para>Using the live file system&mdash;the second of FreeBSD's CDROM
disks&mdash;is useful if you've got limited space. What is on the
live file system varies from release to release. You might try
playing games from the cdrom. This
involves using <command>lndir</>, which gets installed with the X
Window System, to tell the program(s) where to find the necessary
files, because they're in the <filename>/cdrom</filename> file system
instead of in <filename>/usr</filename> and its subdirectories, which
is where they're expected to be. Read <command>man lndir</>.</para>
</chapter>
<chapter>
<title>Comments Welcome</title>
<para>If you use this guide I'd be interested in knowing where it was
unclear and what was left out that you think should be included, and
if it was helpful. My thanks to Eugene W. Stark, professor of
computer science at SUNY-Stony Brook, and John Fieber for helpful
comments.</para>
<para>Annelise Anderson, <email>andrsn@andrsn.stanford.edu</></para>
</chapter>
</book>

6
en/tutorials/ppp/Makefile
View file

@ -1,6 +0,0 @@
# $Id: Makefile,v 1.2 1997-07-01 05:38:16 max Exp $
DOC= ppp
SRCS= ppp.sgml
.include <bsd.sgml.mk>

1734
en/tutorials/ppp/ppp.sgml
View file

File diff suppressed because it is too large Load diff