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

Revert one of my previous changes. Sentences now have two spaces after

Browse source 
the period. Apologies for the repository bloat. This is entirely a
whitespace change.
This commit is contained in:
Nik Clayton 1999-03-04 22:42:55 +00:00
parent 772051fe94
commit fe79ecbe4d
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=4465
88 changed files with 11040 additions and 11040 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -10,13 +10,13 @@
<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
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
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>
@ -47,20 +47,20 @@ host2.foobar.com link#1 UC 0 0
<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
<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
<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
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
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>
@ -69,28 +69,28 @@ host2.foobar.com link#1 UC 0 0
(<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
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
<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
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
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
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>
@ -98,8 +98,8 @@ host2.foobar.com link#1 UC 0 0
<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
<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>
@ -162,14 +162,14 @@ host2.foobar.com link#1 UC 0 0
<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
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
&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
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>
@ -179,7 +179,7 @@ host2.foobar.com link#1 UC 0 0
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
<para>Let us look at an example of default routes. This is a common
configuration:</para>
<literallayout>
@ -187,7 +187,7 @@ host2.foobar.com link#1 UC 0 0
</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
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>
@ -227,13 +227,13 @@ host2.foobar.com link#1 UC 0 0
<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
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
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>
@ -251,20 +251,20 @@ Local1 (10.20.30.1, 10.9.9.30) --&gt; T1-GW (10.9.9.1)
<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
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
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
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>
@ -286,21 +286,21 @@ Local1 (10.20.30.1, 10.9.9.30) --&gt; T1-GW (10.9.9.1)
<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
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
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
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
path inward) for your site. This is known as route
propagation.</para>
</sect2>
@ -309,14 +309,14 @@ Local1 (10.20.30.1, 10.9.9.30) --&gt; T1-GW (10.9.9.1)
<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
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 <citerefentry><refentrytitle>traceroute</refentrytitle><manvolnum>8</manvolnum></citerefentry> command. It is equally
is the <citerefentry><refentrytitle>traceroute</refentrytitle><manvolnum>8</manvolnum></citerefentry> command. It is equally
useful if you cannot seem to make a connection to a remote machine
(ie. <citerefentry><refentrytitle>ping</refentrytitle><manvolnum>8</manvolnum></citerefentry> fails).</para>
(ie. <citerefentry><refentrytitle>ping</refentrytitle><manvolnum>8</manvolnum></citerefentry> fails).</para>
<para>The <citerefentry><refentrytitle>traceroute</refentrytitle><manvolnum>8</manvolnum></citerefentry> command is run with the
name of the remote host you are trying to connect to. It will show
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>
@ -339,38 +339,38 @@ Local1 (10.20.30.1, 10.9.9.30) --&gt; T1-GW (10.9.9.1)
<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
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
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
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
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
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
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
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,
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>
@ -402,18 +402,18 @@ freebox:/sharedfs /project nfs rw,-w=1024 0 0</programlisting>
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
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
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
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
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
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>
@ -425,7 +425,7 @@ freebox:/sharedfs /project nfs rw,-w=1024 0 0</programlisting>
<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,
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>
@ -438,8 +438,8 @@ freebox:/sharedfs /project nfs rw,-w=1024 0 0</programlisting>
<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>
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
@ -453,7 +453,7 @@ freebox:/sharedfs /project nfs rw,-w=1024 0 0</programlisting>
<procedure>
<step>
<para>Find a machine that will be your server. This machine
<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>
@ -466,7 +466,7 @@ freebox:/sharedfs /project nfs rw,-w=1024 0 0</programlisting>
</listitem>
<listitem>
<para>Sun/Solaris 2.3. (you may need to get
<para>Sun/Solaris 2.3. (you may need to get
bootp)</para>
</listitem>
@ -492,12 +492,12 @@ diskless:\
<step>
<para>Set up a TFTP server (on same machine as bootp server)
to provide booting information to client. The name of this
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
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">
@ -611,7 +611,7 @@ hostname myclient.mydomain</programlisting>
<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
<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
@ -650,7 +650,7 @@ hostname myclient.mydomain</programlisting>
<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
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>
@ -679,7 +679,7 @@ hostname myclient.mydomain</programlisting>
<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
<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>
@ -690,7 +690,7 @@ hostname myclient.mydomain</programlisting>
<para>Netboot can be compiled to support NE1000/2000 cards by
changing the configuration in
<filename>/sys/i386/boot/netboot/Makefile</filename>. See the
<filename>/sys/i386/boot/netboot/Makefile</filename>. See the
comments at the top of this file.</para>
</sect2>
@ -718,7 +718,7 @@ hostname myclient.mydomain</programlisting>
<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
Adapters. This will give you the most flexibility, with the
fewest problems, if you change providers.</para>
</listitem>
@ -731,7 +731,7 @@ hostname myclient.mydomain</programlisting>
</itemizedlist>
<para>Cost is a significant factor in determining what solution you
will choose. The following options are listed from least expensive
will choose. The following options are listed from least expensive
to most expensive.</para>
@ -741,10 +741,10 @@ hostname myclient.mydomain</programlisting>
<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>
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
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>
@ -753,17 +753,17 @@ hostname myclient.mydomain</programlisting>
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
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
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
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>
@ -773,7 +773,7 @@ hostname myclient.mydomain</programlisting>
enhancing isdn4bsd, please get in touch with
<email>hm@kts.org</email>.</para>
<para>A majordomo maintained mailing list is available. To join the
<para>A majordomo maintained mailing list is available. To join the
list, send mail to <email>majordomo@FreeBSD.ORG</email> and
specify:</para>
@ -794,21 +794,21 @@ subscribe freebsd-isdn</programlisting>
<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>
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
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
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
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
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
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>
@ -850,8 +850,8 @@ subscribe freebsd-isdn</programlisting>
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
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>
@ -860,8 +860,8 @@ subscribe freebsd-isdn</programlisting>
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
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>
@ -871,7 +871,7 @@ subscribe freebsd-isdn</programlisting>
<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
any other operating system. For a more complete description of
routing and bridging technology, please refer to a Networking
reference book.</para>
@ -879,10 +879,10 @@ subscribe freebsd-isdn</programlisting>
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
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
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
@ -890,13 +890,13 @@ subscribe freebsd-isdn</programlisting>
connection.</para>
<para>The main problem with ISDN routers and bridges is that
interoperability between manufacturers can still be a problem. If
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
maintenance solution. Since you are buying the equipment for both
sides of the connection you can be assured that the link will
work.</para>
@ -907,7 +907,7 @@ subscribe freebsd-isdn</programlisting>
<example>
<title>Branch office or Home network</title>
<para>Network is 10 Base T Ethernet. Connect router to network
<para>Network is 10 Base T Ethernet. Connect router to network
cable with AUI/10BT transceiver, if necessary.</para>
<!-- This should be a graphic -->
@ -949,7 +949,7 @@ ISDN BRI line</programlisting>
<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,
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>
@ -958,7 +958,7 @@ ISDN BRI line</programlisting>
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
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>

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

@ -9,7 +9,7 @@
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
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>
@ -41,22 +41,22 @@
Storage)</title>
<para>4mm tapes are replacing QIC as the workstation backup media of
choice. This trend accelerated greatly when Conner purchased Archive,
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
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
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
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
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
<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
@ -67,23 +67,23 @@
<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
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
<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>
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
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>
@ -92,31 +92,31 @@
<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
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
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
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
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;
<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
<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
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>
@ -133,25 +133,25 @@
<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
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
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.
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>
@ -161,7 +161,7 @@
<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
completely blank tape, the operation will fail. The console
messages should be similar to:</para>
@ -171,7 +171,7 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
<para>The tape does not contain an Identifier Block (block number 0).
All QIC tape drives since the adoption of QIC-525 standard write an
Identifier Block to the tape. There are two solutions:</para>
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>
@ -220,7 +220,7 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
</citerefentry> and <citerefentry>
<refentrytitle>restore</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry> are the traditional Unix backup programs. They operate
</citerefentry> 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.
<citerefentry>
@ -237,13 +237,13 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
<manvolnum>8</manvolnum>
</citerefentry> does not write files and directories to tape, but
rather writes the data blocks that are the building blocks of files
and directories. <citerefentry>
and directories. <citerefentry>
<refentrytitle>dump</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry> has quirks that remain from its early days in
Version 6 of ATT Unix (circa 1975). The default parameters are
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
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>
@ -253,28 +253,28 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
</citerefentry> and <citerefentry>
<refentrytitle>rrestore</refentrytitle>
<manvolnum>8</manvolnum></citerefentry> backup data across the
network to a tape drive attached to another computer. Both programs
network to a tape drive attached to another computer. Both programs
rely upon <citerefentry>
<refentrytitle>rcmd</refentrytitle>
<manvolnum>3</manvolnum>
</citerefentry> and <citerefentry>
<refentrytitle>ruserok</refentrytitle>
<manvolnum>3</manvolnum></citerefentry> to access the remote tape
drive. Therefore, the user performing the backup must have
<literal>rhosts</literal> access to the remote computer. The
drive. Therefore, the user performing the backup must have
<literal>rhosts</literal> access to the remote computer. The
arguments to <citerefentry>
<refentrytitle>rdump</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry> and <citerefentry>
<refentrytitle>rrestore</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry> must suitable to use on the remote computer. (e.g.
</citerefentry> must suitable to use on the remote computer. (e.g.
When <command>rdump</command>'ing from a FreeBSD computer to an
Exabyte tape drive connected to a Sun called
<hostid>komodo</hostid>, use: <command>/sbin/rdump 0dsbfu 54000
13000 126 komodo:/dev/nrst8 /dev/rsd0a 2>&amp;1</command>) Beware:
there are security implications to allowing <literal>rhosts</literal>
commands. Evaluate your situation carefully.</para>
commands. Evaluate your situation carefully.</para>
</sect2>
<sect2>
@ -284,7 +284,7 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
<refentrytitle>tar</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry> also dates back to Version 6 of ATT Unix (circa
1975). <citerefentry>
1975). <citerefentry>
<refentrytitle>tar</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry> operates in cooperation with the filesystem;
@ -309,21 +309,21 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
<para>Most versions of <citerefentry>
<refentrytitle>tar</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry> do not support backups across the network. The GNU
</citerefentry> do not support backups across the network. The GNU
version of <citerefentry>
<refentrytitle>tar</refentrytitle>
<manvolnum>1</manvolnum></citerefentry>, which FreeBSD utilizes,
supports remote devices using the same syntax as
<command>rdump</command>. To <citerefentry>
<command>rdump</command>. To <citerefentry>
<refentrytitle>tar</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry> to an Exabyte tape drive connected to a Sun called
komodo, use: <command>/usr/bin/tar cf komodo:/dev/nrst8 .
2>&amp;1</command>. For versions without remote device support,
2>&amp;1</command>. For versions without remote device support,
you can use a pipeline and <citerefentry>
<refentrytitle>rsh</refentrytitle>
<manvolnum>1</manvolnum></citerefentry> to send the data to a
remote tape drive. (XXX add an example command)</para>
remote tape drive. (XXX add an example command)</para>
</sect2>
<sect2>
@ -332,15 +332,15 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
<para><citerefentry>
<refentrytitle>cpio</refentrytitle>
<manvolnum>1</manvolnum></citerefentry> is the original Unix
file interchange tape program for magnetic media. <citerefentry>
file interchange tape program for magnetic media. <citerefentry>
<refentrytitle>cpio</refentrytitle>
<manvolnum>1</manvolnum></citerefentry> 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
archives format, and pipe the data to other programs. This last
feature makes <citerefentry>
<refentrytitle>cpio</refentrytitle>
<manvolnum>1</manvolnum></citerefentry> and excellent choice for
installation media. <citerefentry>
installation media. <citerefentry>
<refentrytitle>cpio</refentrytitle>
<manvolnum>1</manvolnum></citerefentry> does not know how to walk
the directory tree and a list of files must be provided thru
@ -349,10 +349,10 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
<para><citerefentry>
<refentrytitle>cpio</refentrytitle>
<manvolnum>1</manvolnum></citerefentry> does not support backups
across the network. You can use a pipeline and <citerefentry>
across the network. You can use a pipeline and <citerefentry>
<refentrytitle>rsh</refentrytitle>
<manvolnum>1</manvolnum></citerefentry> to send the data to a
remote tape drive. (XXX add an example command)</para>
remote tape drive. (XXX add an example command)</para>
</sect2>
<sect2>
@ -361,12 +361,12 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
<para><citerefentry>
<refentrytitle>pax</refentrytitle>
<manvolnum>1</manvolnum></citerefentry> is IEEE/POSIX's answer to
<command>tar</command> and <command>cpio</command>. Over the years the
<command>tar</command> and <command>cpio</command>. Over the years the
various versions of <command>tar</command> and <command>cpio</command>
have gotten slightly incompatible. So rather than fight it out to
have gotten slightly incompatible. So rather than fight it out to
fully standardize them, POSIX created a new archive utility.
<command>pax</command> attempts to read and write many of the various
cpio and tar formats, plus new formats of its own. Its command set
cpio and tar formats, plus new formats of its own. Its command set
more resembles <command>cpio</command> than
<command>tar</command>.</para>
</sect2>
@ -376,23 +376,23 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
<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
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
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
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
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
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>
@ -400,22 +400,22 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
<title>Do nothing</title>
<para>&ldquo;Do nothing&rdquo; is not a computer program, but it is the
most widely used backup strategy. There are no initial costs. There is
no backup schedule to follow. Just say no. If something happens to
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
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
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> 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>
@ -426,17 +426,17 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
<refentrytitle>dump</refentrytitle>
<manvolnum>8</manvolnum></citerefentry> <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
here. The clear choice for preserving all your data and all the
peculiarities of Unix filesystems is <citerefentry>
<refentrytitle>dump</refentrytitle>
<manvolnum>8</manvolnum></citerefentry>. Elizabeth created
<manvolnum>8</manvolnum></citerefentry>. 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
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
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>
@ -457,14 +457,14 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
<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
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
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:
access your tape drive. These floppies must contain:
<citerefentry>
<refentrytitle>fdisk</refentrytitle>
<manvolnum>8</manvolnum></citerefentry>, <citerefentry>
@ -474,7 +474,7 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
<manvolnum>8</manvolnum></citerefentry>, <citerefentry>
<refentrytitle>mount</refentrytitle>
<manvolnum>8</manvolnum></citerefentry>, and whichever backup
program you use. These programs must be statically linked. If you
program you use. These programs must be statically linked. If you
use <citerefentry>
<refentrytitle>dump</refentrytitle>
<manvolnum>8</manvolnum></citerefentry>, the floppy must contain
@ -482,25 +482,25 @@ st0(ncr1:4:0): Logical unit is in process of becoming ready</screen>
<refentrytitle>restore</refentrytitle>
<manvolnum>8</manvolnum></citerefentry>.</para>
<para>Third, create backup tapes regularly. Any changes that you make
after your last backup may be irretrievably lost. Write-protect the
<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
floppies you made in step two.) and backup tapes. Make notes of the
procedure. Store these notes with the bootable floppy, the printouts
and the backup tapes. You will be so distraught when restoring that
the notes may prevent you from destroying your backup tapes (How?
In place of <command>tar xvf /dev/rst0</command>, you might
accidently type <command>tar cvf /dev/rst0</command> and over-write
your backup tape).</para>
<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
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
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>
@ -666,20 +666,20 @@ chmod 644 /mnt/etc/passwd
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
<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
<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
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>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
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>
@ -690,23 +690,23 @@ chmod 644 /mnt/etc/passwd
<refentrytitle>mount</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry>(e.g. <command>mount /dev/sd0a
/mnt</command>) the root partition of your first disk. If the
/mnt</command>) the root partition of your first disk. If the
disklabel was damaged, use <citerefentry>
<refentrytitle>disklabel</refentrytitle>
<manvolnum>8</manvolnum></citerefentry> to re-partition and
label the disk to match the label that your printed and saved. Use
label the disk to match the label that your printed and saved. Use
<citerefentry>
<refentrytitle>newfs</refentrytitle>
<manvolnum>8</manvolnum></citerefentry> 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
filesystems. Re-mount the root partition of the floppy read-write
(<command>mount -u -o rw /mnt</command>). Use your backup program
and backup tapes to recover the data for this filesystem (e.g.
<command>restore vrf /dev/st0</command>). Unmount the filesystem
<command>restore vrf /dev/st0</command>). Unmount the filesystem
(e.g. <command>umount /mnt</command>) Repeat for each filesystem
that was damaged.</para>
<para>Once your system is running, backup your data onto new tapes.
Whatever caused the crash or data loss may strike again. An another
Whatever caused the crash or data loss may strike again. An another
hour spent now, may save you from further distress later.</para>
</sect3>

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

@ -6,11 +6,11 @@
<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
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
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>
command. Use of the <command>man</command> command is simple:</para>
<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput>
@ -18,7 +18,7 @@
<para><replaceable>command</replaceable> is
the name of the command you wish to learn about. For example, to
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>
@ -63,9 +63,9 @@
</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
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
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>
@ -74,7 +74,7 @@
<para>This will display the manual page for the user
command <command>chmod</command>. References to a
command <command>chmod</command>. References to a
particular section of the on-line manual are traditionally placed in
parenthesis in written documentation, so <citerefentry><refentrytitle>chmod</refentrytitle><manvolnum>1</manvolnum></citerefentry> refers to the
<command>chmod</command>
@ -116,7 +116,7 @@
<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
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
@ -128,7 +128,7 @@
<screen>&prompt.user; <userinput>info</userinput></screen>
<para>For a brief introduction, type <userinput>h</userinput>. For a quick
<para>For a brief introduction, type <userinput>h</userinput>. For a quick
command reference, type <userinput>?</userinput>.</para>
</sect1>

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

@ -4,7 +4,7 @@
<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
operating system run smoothly. For this, there is no substitute for a
good book on UNIX system administration and a good users'
manual.</para>
@ -26,33 +26,33 @@
<listitem>
<para>FreeBSD for PC 98'ers (in Japanese), published by SHUWA
System Co, LTD. ISBN 4-87966-468-5 C3055 P2900E.</para>
System Co, LTD. ISBN 4-87966-468-5 C3055 P2900E.</para>
</listitem>
<listitem>
<para>FreeBSD (in Japanese), published by CUTT. ISBN
<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>
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>
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
<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>
Literatur Verlag/Vertrieb Hanser, 1998. ISBN 3-932311-31-0.</para>
</listitem>
<listitem>
@ -90,27 +90,27 @@
<itemizedlist>
<listitem>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD User's Reference Manual</emphasis>. O'Reilly
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD User's Reference Manual</emphasis>. O'Reilly
&amp; Associates, Inc., 1994.<!-- <br> --> ISBN
1-56592-075-9</para>
</listitem>
<listitem>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD User's Supplementary Documents</emphasis>.
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD User's Supplementary Documents</emphasis>.
O'Reilly &amp; Associates, Inc., 1994.<!-- <br> --> ISBN
1-56592-076-7</para>
</listitem>
<listitem>
<para><emphasis>UNIX in a Nutshell</emphasis>. O'Reilly
<para><emphasis>UNIX in a Nutshell</emphasis>. O'Reilly
&amp; Associates, Inc., 1990.<!-- <br> --> ISBN
093717520X</para>
</listitem>
<listitem>
<para>Mui, Linda. <emphasis>What You Need To Know When You Can't
Find Your UNIX System Administrator</emphasis>. O'Reilly
&amp; Associates, Inc., 1995. <!-- <br> --> ISBN 1-56592-104-6</para>
<para>Mui, Linda. <emphasis>What You Need To Know When You Can't
Find Your UNIX System Administrator</emphasis>. O'Reilly
&amp; Associates, Inc., 1995. <!-- <br> --> ISBN 1-56592-104-6</para>
</listitem>
<listitem>
@ -121,11 +121,11 @@
<listitem>
<para><ulink url="http://www.jp.FreeBSD.ORG/">Jpman Project,
Japan FreeBSD Users Group</ulink>. <ulink
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
Communications Inc.</ulink>, 1998. ISBN4-8399-0088-4
P3800E.</para>
</listitem>
</itemizedlist>
@ -140,54 +140,54 @@
<itemizedlist>
<listitem>
<para>Albitz, Paul and Liu, Cricket. <emphasis>DNS and
<para>Albitz, Paul and Liu, Cricket. <emphasis>DNS and
BIND</emphasis>, 2nd Ed. O'Reilly &amp; Associates, Inc.,
1997. <!-- <br> --> ISBN 1-56592-236-0</para>
1997. <!-- <br> --> ISBN 1-56592-236-0</para>
</listitem>
<listitem>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD System Manager's Manual</emphasis>. O'Reilly
&amp; Associates, Inc., 1994. <!-- <br> --> ISBN
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD System Manager's Manual</emphasis>. O'Reilly
&amp; Associates, Inc., 1994. <!-- <br> --> ISBN
1-56592-080-5</para>
</listitem>
<listitem>
<para>Costales, Brian, et al. <emphasis>Sendmail</emphasis>, 2nd
<para>Costales, Brian, et al. <emphasis>Sendmail</emphasis>, 2nd
Ed. O'Reilly &amp; Associates, Inc., 1997.<!-- <br> --> ISBN
1-56592-222-0</para>
</listitem>
<listitem>
<para>Frisch, &AElig;leen. <emphasis>Essential System
<para>Frisch, &AElig;leen. <emphasis>Essential System
Administration</emphasis>, 2nd Ed. O'Reilly &amp;
Associates, Inc., 1995. <!-- <br> -->ISBN 1-56592-127-5</para>
Associates, Inc., 1995. <!-- <br> -->ISBN 1-56592-127-5</para>
</listitem>
<listitem>
<para>Hunt, Craig. <emphasis>TCP/IP Network
Administration</emphasis>. O'Reilly &amp; Associates, Inc.,
1992. <!-- <br> --> ISBN 0-937175-82-X</para>
<para>Hunt, Craig. <emphasis>TCP/IP Network
Administration</emphasis>. O'Reilly &amp; Associates, Inc.,
1992. <!-- <br> --> ISBN 0-937175-82-X</para>
</listitem>
<listitem>
<para>Nemeth, Evi. <emphasis>UNIX System Administration
Handbook</emphasis>. 2nd Ed. Prentice Hall, 1995. <!-- <br>
<para>Nemeth, Evi. <emphasis>UNIX System Administration
Handbook</emphasis>. 2nd Ed. Prentice Hall, 1995. <!-- <br>
--> ISBN 0131510517</para>
</listitem>
<listitem>
<para>Stern, Hal <emphasis>Managing NFS and NIS</emphasis>
O'Reilly &amp; Associates, Inc., 1991. <!-- <br> --> ISBN
O'Reilly &amp; Associates, Inc., 1991. <!-- <br> --> ISBN
0-937175-75-7</para>
</listitem>
<listitem>
<para><ulink url="http://www.jp.FreeBSD.ORG/">Jpman Project,
Japan FreeBSD Users Group</ulink>. <ulink
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
Communications Inc.</ulink>, 1998. ISBN4-8399-0109-0
P3300E.</para>
</listitem>
</itemizedlist>
@ -202,61 +202,61 @@
<itemizedlist>
<listitem>
<para>Asente, Paul. <emphasis>X Window System
Toolkit</emphasis>. Digital Press. <!-- <br> --> ISBN
<para>Asente, Paul. <emphasis>X Window System
Toolkit</emphasis>. Digital Press. <!-- <br> --> ISBN
1-55558-051-3</para>
</listitem>
<listitem>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD Programmer's Reference Manual</emphasis>.
O'Reilly &amp; Associates, Inc., 1994. <!-- <br> --> ISBN
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD Programmer's Reference Manual</emphasis>.
O'Reilly &amp; Associates, Inc., 1994. <!-- <br> --> ISBN
1-56592-078-3</para>
</listitem>
<listitem>
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD Programmer's Supplementary
Documents</emphasis>. O'Reilly &amp; Associates, Inc., 1994.
<para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD Programmer's Supplementary
Documents</emphasis>. O'Reilly &amp; Associates, Inc., 1994.
<!-- <br> --> ISBN 1-56592-079-1</para>
</listitem>
<listitem>
<para>Harbison, Samuel P. and Steele, Guy L. Jr. <emphasis>C: A
Reference Manual</emphasis>. 4rd ed. Prentice Hall, 1995.
<para>Harbison, Samuel P. and Steele, Guy L. Jr. <emphasis>C: A
Reference Manual</emphasis>. 4rd ed. Prentice Hall, 1995.
<!-- <br> -->ISBN 0-13-326224-3</para>
</listitem>
<listitem>
<para>Kernighan, Brian and Dennis M. Ritchie. <emphasis>The C
Programming Language.</emphasis>. PTR Prentice Hall, 1988.
<para>Kernighan, Brian and Dennis M. Ritchie. <emphasis>The C
Programming Language.</emphasis>. PTR Prentice Hall, 1988.
<!-- <br> --> ISBN 0-13-110362-9</para>
</listitem>
<listitem>
<para>Lehey, Greg. <emphasis>Porting UNIX Software</emphasis>.
<para>Lehey, Greg. <emphasis>Porting UNIX Software</emphasis>.
O'Reilly &amp; Associates, Inc., 1995.<!-- <br> --> ISBN
1-56592-126-7</para>
</listitem>
<listitem>
<para>Plauger, P. J. <emphasis>The Standard C
Library</emphasis>. Prentice Hall, 1992. <!-- <br> --> ISBN
Library</emphasis>. Prentice Hall, 1992. <!-- <br> --> ISBN
0-13-131509-9</para>
</listitem>
<listitem>
<para>Stevens, W. Richard. <emphasis>Advanced Programming in the
UNIX Environment</emphasis>. Reading, Mass. :
<para>Stevens, W. Richard. <emphasis>Advanced Programming in the
UNIX Environment</emphasis>. Reading, Mass. :
Addison-Wesley, 1992<!-- <br> --> ISBN 0-201-56317-7</para>
</listitem>
<listitem>
<para>Stevens, W. Richard. <emphasis>UNIX Network
Programming</emphasis>. 2nd Ed, PTR Prentice Hall, 1998. ISBN
<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;.
<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>
@ -273,66 +273,66 @@
<itemizedlist>
<listitem>
<para>Andleigh, Prabhat K. <emphasis>UNIX System
Architecture</emphasis>. Prentice-Hall, Inc., 1990.<!-- <br>
<para>Andleigh, Prabhat K. <emphasis>UNIX System
Architecture</emphasis>. Prentice-Hall, Inc., 1990.<!-- <br>
--> ISBN 0-13-949843-5</para>
</listitem>
<listitem>
<para>Jolitz, William. &ldquo;Porting UNIX to the
<para>Jolitz, William. &ldquo;Porting UNIX to the
386&rdquo;. <emphasis>Dr.
Dobb's Journal</emphasis>. January 1991-July 1992.</para>
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,
System</emphasis>. Reading, Mass. : Addison-Wesley,
1989.<!-- <br> --> ISBN 0-201-06196-1</para>
</listitem>
<listitem>
<para>Leffler, Samuel J., Marshall Kirk McKusick, <emphasis>The
Design and Implementation of the 4.3BSD UNIX Operating
System: Answer Book</emphasis>. Reading, Mass. :
System: Answer Book</emphasis>. Reading, Mass. :
Addison-Wesley, 1991.<!-- <br> --> ISBN 0-201-54629-9</para>
</listitem>
<listitem>
<para>McKusick, Marshall Kirk, Keith Bostic, Michael J Karels,
and John Quarterman. <emphasis>The Design and Implementation
of the 4.4BSD Operating System</emphasis>. Reading, Mass. :
and John Quarterman. <emphasis>The Design and Implementation
of the 4.4BSD Operating System</emphasis>. Reading, Mass. :
Addison-Wesley, 1996.<!-- <br> --> ISBN 0-201-54979-4</para>
</listitem>
<listitem>
<para>Stevens, W. Richard. <emphasis>TCP/IP Illustrated, Volume
1: The Protocols</emphasis>. Reading, Mass. :
<para>Stevens, W. Richard. <emphasis>TCP/IP Illustrated, Volume
1: The Protocols</emphasis>. Reading, Mass. :
Addison-Wesley, 1996.<!-- <br> --> ISBN 0-201-63346-9</para>
</listitem>
<listitem>
<para>Schimmel, Curt. <emphasis>Unix Systems for Modern
Architectures</emphasis>. Reading, Mass. : Addison-Wesley,
1994. ISBN 0-201-63338-8</para>
<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
<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,
Protocols</emphasis>. Reading, Mass. : Addison-Wesley,
1996.<!-- <br> --> ISBN 0-201-63495-3</para>
</listitem>
<listitem>
<para>Vahalia, Uresh. <emphasis>UNIX Internals -- The New
Frontiers</emphasis>. Prentice Hall, 1996.<!-- <br> --> ISBN
<para>Vahalia, Uresh. <emphasis>UNIX Internals -- The New
Frontiers</emphasis>. Prentice Hall, 1996.<!-- <br> --> ISBN
0-13-101908-2</para>
</listitem>
<listitem>
<para>Wright, Gary R. and W. Richard Stevens. <emphasis>TCP/IP
<para>Wright, Gary R. and W. Richard Stevens. <emphasis>TCP/IP
Illustrated, Volume 2: The Implementation</emphasis>.
Reading, Mass. : Addison-Wesley, 1995.<!-- <br> --> ISBN
0-201-63354-X</para>
@ -352,18 +352,18 @@
<listitem>
<para>Cheswick, William R. and Steven M. Bellovin.
<emphasis>Firewalls and Internet Security: Repelling the Wily
Hacker</emphasis>. Reading, Mass. : Addison-Wesley,
Hacker</emphasis>. Reading, Mass. : Addison-Wesley,
1995.<!-- <br> --> ISBN 0-201-63357-4</para>
</listitem>
<listitem>
<para>Garfinkel, Simson and Gene Spafford. <emphasis>Practical
UNIX Security</emphasis>. 2nd Ed. O'Reilly &amp; Associates,
Inc., 1996. <!-- <br> --> ISBN 1-56592-148-8</para>
<para>Garfinkel, Simson and Gene Spafford. <emphasis>Practical
UNIX Security</emphasis>. 2nd Ed. O'Reilly &amp; Associates,
Inc., 1996. <!-- <br> --> ISBN 1-56592-148-8</para>
</listitem>
<listitem>
<para>Garfinkel, Simson. <emphasis>PGP Pretty Good
<para>Garfinkel, Simson. <emphasis>PGP Pretty Good
Privacy</emphasis> O'Reilly &amp; Associates, Inc., 1995.
<!-- <br> --> ISBN 1-56592-098-8</para>
</listitem>
@ -380,14 +380,14 @@
<itemizedlist>
<listitem>
<para>Anderson, Don and Tom Shanley. <emphasis>Pentium Processor
System Architecture</emphasis>. 2nd Ed. Reading, Mass. :
<para>Anderson, Don and Tom Shanley. <emphasis>Pentium Processor
System Architecture</emphasis>. 2nd Ed. Reading, Mass. :
Addison-Wesley, 1995.<!-- <br> --> 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,
<para>Ferraro, Richard F. <emphasis>Programmer's Guide to the
EGA, VGA, and Super VGA Cards</emphasis>. 3rd ed. Reading,
Mass. : Addison-Wesley, 1995.<!-- <br> --> ISBN
0-201-62490-7</para>
</listitem>
@ -400,26 +400,26 @@
</listitem>
<listitem>
<para>Shanley, Tom. <emphasis>80486 System
Architecture</emphasis>. 3rd ed. Reading, Mass. :
Addison-Wesley, 1995. <!-- <br> -->ISBN 0-201-40994-1</para>
<para>Shanley, Tom. <emphasis>80486 System
Architecture</emphasis>. 3rd ed. Reading, Mass. :
Addison-Wesley, 1995. <!-- <br> -->ISBN 0-201-40994-1</para>
</listitem>
<listitem>
<para>Shanley, Tom. <emphasis>ISA System
Architecture</emphasis>. 3rd ed. Reading, Mass. :
<para>Shanley, Tom. <emphasis>ISA System
Architecture</emphasis>. 3rd ed. Reading, Mass. :
Addison-Wesley, 1995.<!-- <br> --> ISBN 0-201-40996-8</para>
</listitem>
<listitem>
<para>Shanley, Tom. <emphasis>PCI System
Architecture</emphasis>. 3rd ed. Reading, Mass. :
Addison-Wesley, 1995. <!-- <br> -->ISBN 0-201-40993-3</para>
<para>Shanley, Tom. <emphasis>PCI System
Architecture</emphasis>. 3rd ed. Reading, Mass. :
Addison-Wesley, 1995. <!-- <br> -->ISBN 0-201-40993-3</para>
</listitem>
<listitem>
<para>Van Gilluwe, Frank. <emphasis>The Undocumented
PC</emphasis>. Reading, Mass: Addison-Wesley Pub. Co.,
<para>Van Gilluwe, Frank. <emphasis>The Undocumented
PC</emphasis>. Reading, Mass: Addison-Wesley Pub. Co.,
1994.<!-- <br> --> ISBN 0-201-62277-7</para>
</listitem>
@ -436,45 +436,45 @@
<listitem>
<para>Lion, John <emphasis>Lion's Commentary on UNIX, 6th Ed.
With Source Code</emphasis>. ITP Media Group, 1996.<!-- <br>
With Source Code</emphasis>. ITP Media Group, 1996.<!-- <br>
--> ISBN 1573980137</para>
</listitem>
<listitem>
<para>Raymond, Eric s. <emphasis>The New Hacker's Dictonary, 3rd
edition</emphasis>. MIT Press, 1996.<!-- <br> --> ISBN
<para>Raymond, Eric s. <emphasis>The New Hacker's Dictonary, 3rd
edition</emphasis>. MIT Press, 1996.<!-- <br> --> ISBN
0-262-68092-0<!-- <br> --> Also known as the <ulink
URL="http://www.ccil.org/jargon/jargon.html">Jargon
File</ulink></para>
</listitem>
<listitem>
<para>Salus, Peter H. <emphasis>A quarter century of
UNIX</emphasis>. Addison-Wesley Publishing Company, Inc.,
<para>Salus, Peter H. <emphasis>A quarter century of
UNIX</emphasis>. Addison-Wesley Publishing Company, Inc.,
1994.<!-- <br> --> ISBN 0-201-54777-5</para>
</listitem>
<listitem>
<para>Simon Garfinkel, Daniel Weise, Steven Strassmann.
<emphasis>The UNIX-HATERS Handbook</emphasis>. IDG Books
<emphasis>The UNIX-HATERS Handbook</emphasis>. IDG Books
Worldwide, Inc., 1994.<!-- <br> --> ISBN 1-56884-203-1</para>
</listitem>
<listitem>
<para>Don Libes, Sandy Ressler <emphasis>Life with
UNIX</emphasis> &mdash; special edition. Prentice-Hall, Inc.,
UNIX</emphasis> &mdash; special edition. Prentice-Hall, Inc.,
1989.<!-- <br> --> ISBN 0-13-536657-7</para>
</listitem>
<listitem>
<para><emphasis>The BSD family tree</emphasis>. 1997.<!-- <br>
<para><emphasis>The BSD family tree</emphasis>. 1997.<!-- <br>
--> <ulink
url="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/misc/bsd-family-tree">ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/misc/bsd-family-tree</ulink> or <ulink URL="file:/usr/share/misc/bsd-family-tree">local</ulink> on a FreeBSD-current machine.</para>
</listitem>
<listitem>
<para><emphasis>The BSD Release Announcements
collection</emphasis>. 1997.<!-- <br> --> <ulink
collection</emphasis>. 1997.<!-- <br> --> <ulink
URL="http://www.de.FreeBSD.ORG/de/ftp/releases/">http://www.de.FreeBSD.ORG/de/ftp/releases/</ulink></para>
</listitem>
@ -486,8 +486,8 @@ url="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/misc/bsd-family
<listitem>
<para><emphasis>Old BSD releases from the Computer Systems Research
group (CSRG)</emphasis>. <ulink
url="http://www.mckusick.com/csrg/">http://www.mckusick.com/csrg/</ulink>: The 4CD set covers all BSD versions from 1BSD to 4.4BSD and 4.4BSD-Lite2 (but not 2.11BSD, unfortunately). As well, the last disk holds the final sources plus the SCCS files.</para>
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>
@ -501,8 +501,8 @@ url="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/misc/bsd-family
<itemizedlist>
<listitem>
<para><emphasis>The C/C++ Users Journal</emphasis>. R&amp;D
Publications Inc. ISSN 1075-2838</para>
<para><emphasis>The C/C++ Users Journal</emphasis>. R&amp;D
Publications Inc. ISSN 1075-2838</para>
</listitem>
<listitem>

6
en/handbook/boothelp.sgml
View file

@ -15,11 +15,11 @@
<abstract>
<para>Welcome to FreeBSD! This guide describes the FreeBSD installation
process. To navigate through through the section in this guide using
process. To navigate through through the section in this guide using
the <emphasis>up</emphasis> and <emphasis>down</emphasis> arrow keys
to select the section you wish to read. THen use the <emphasis>right
to select the section you wish to read. THen use the <emphasis>right
arrow</emphasis> or the <emphasis>enter key</emphasis> to view the
section. You can backtract through section you have read by using the
section. You can backtract through section you have read by using the
<emphasis>left arrow</emphasis>.</abstract>
</abstract>
</bookinfo>

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

@ -6,12 +6,12 @@
<para>So you want to contribute something to FreeBSD? That is great! We
can always use the help, and FreeBSD is one of those systems that
<emphasis>relies</emphasis> on the contributions of its user base in
order to survive. Your contributions are not only appreciated, they
order to survive. Your contributions are not only appreciated, they
are vital to FreeBSD's continued growth!</para>
<para>Contrary to what some people might also have you believe, you do
not need to be a hot-shot programmer or a close personal friend of the
FreeBSD core team in order to have your contributions accepted. The
FreeBSD core team in order to have your contributions accepted. The
FreeBSD Project's development is done by a large and growing number of
international contributors whose ages and areas of technical expertise
vary greatly, and there is always more work to be done than there are
@ -21,16 +21,16 @@
system environment (and its installation) rather than just a kernel or
a few scattered utilities, our <filename>TODO</filename> list also spans a very wide
range of tasks, from documentation, beta testing and presentation to
highly specialized types of kernel development. No matter what your
highly specialized types of kernel development. No matter what your
skill level, there is almost certainly something you can do to help
the project!</para>
<para>Commercial entities engaged in FreeBSD-related enterprises are
also encouraged to contact us. Need a special extension to make your
also encouraged to contact us. Need a special extension to make your
product work? You will find us receptive to your requests, given that
they are not too outlandish. Working on a value-added product?
they are not too outlandish. Working on a value-added product?
Please let us know! We may be able to work cooperatively on some
aspect of it. The free software world is challenging a lot of
aspect of it. The free software world is challenging a lot of
existing assumptions about how software is developed, sold, and
maintained throughout its life cycle, and we urge you to at least give
it a second look.</para>
@ -41,10 +41,10 @@
<para>The following list of tasks and sub-projects represents
something of an amalgam of the various core team <filename>TODO</filename> lists and user
requests we have collected over the last couple of months. Where
possible, tasks have been ranked by degree of urgency. If you are
requests we have collected over the last couple of months. Where
possible, tasks have been ranked by degree of urgency. If you are
interested in working on one of the tasks you see here, send mail to
the coordinator listed by clicking on their names. If no
the coordinator listed by clicking on their names. If no
coordinator has been appointed, maybe you would like to
volunteer?</para>
@ -59,7 +59,7 @@
<orderedlist>
<listitem>
<para>3-stage boot issues. Overall coordination:
<para>3-stage boot issues. Overall coordination:
&a.hackers;</para>
@ -75,7 +75,7 @@
</listitem>
<listitem>
<para>Filesystem problems. Overall coordination: &a.fs;</para>
<para>Filesystem problems. Overall coordination: &a.fs;</para>
<itemizedlist>
<listitem>
@ -88,7 +88,7 @@
</listitem>
<listitem>
<para>Fix the union file system. Coordinator:
<para>Fix the union file system. Coordinator:
&a.dg;</para>
</listitem>
@ -97,12 +97,12 @@
</listitem>
<listitem>
<para>Implement Int13 vm86 disk driver. Coordinator:
<para>Implement Int13 vm86 disk driver. Coordinator:
&a.hackers;</para>
</listitem>
<listitem>
<para>New bus architecture. Coordinator: &a.newbus;</para>
<para>New bus architecture. Coordinator: &a.newbus;</para>
<itemizedlist>
<listitem>
@ -116,7 +116,7 @@
</listitem>
<listitem>
<para>Port PCI subsystem to new architecture. Coordinator:
<para>Port PCI subsystem to new architecture. Coordinator:
&a.dfr;</para>
</listitem>
@ -139,7 +139,7 @@
</listitem>
<listitem>
<para>Kernel issues. Overall coordination: &a.hackers;</para>
<para>Kernel issues. Overall coordination: &a.hackers;</para>
</listitem>
<listitem>
@ -156,7 +156,7 @@
<listitem>
<para>Make the entire kernel use
<literal>suser()</literal> instead of comparing to 0. It
<literal>suser()</literal> instead of comparing to 0. It
is presently using about half of each. Coordinator:
&a.eivind;</para>
</listitem>
@ -164,7 +164,7 @@
<listitem>
<para>Split securelevels into different parts, to allow an
administrator to throw away those privileges he can throw
away. Setting the overall securelevel needs to have the
away. Setting the overall securelevel needs to have the
same effect as now, obviously. Coordinator:
&a.eivind;</para>
</listitem>
@ -196,7 +196,7 @@
<para>Add code to teh NFS layer so that you cannot
<literal>chdir("..")</literal> out of an NFS partition.
E.g., <filename>/usr</filename> is a UFS partition with
<filename>/usr/src</filename> NFS exported. Now it is
<filename>/usr/src</filename> NFS exported. Now it is
possible to use the NFS filehandle for
<filename>/usr/src</filename> to get access to
<filename>/usr</filename>.</para>
@ -230,7 +230,7 @@
</listitem>
<listitem>
<para>PCMCIA/PCCARD. Coordinators: &a.msmith; and &a.phk;</para>
<para>PCMCIA/PCCARD. Coordinators: &a.msmith; and &a.phk;</para>
<itemizedlist>
<listitem>
@ -267,7 +267,7 @@
</listitem>
<listitem>
<para>Advanced Power Management. Coordinators: &a.msmith; and
<para>Advanced Power Management. Coordinators: &a.msmith; and
&a.phk;</para>
<itemizedlist>
@ -310,7 +310,7 @@
<listitem>
<para>NetWare Server (protected mode ODI driver) loader and
subservices to allow the use of ODI card drivers supplied
with network cards. The same thing for NDIS drivers and
with network cards. The same thing for NDIS drivers and
NetWare SCSI drivers.</para>
</listitem>
@ -327,7 +327,7 @@
<listitem>
<para>A concerted effort at support for portable computers.
This is somewhat handled by changing PCMCIA bridging rules
and power management event handling. But there are things
and power management event handling. But there are things
like detecting internal vs. external display and picking a
different screen resolution based on that fact, not spinning
down the disk if the machine is in dock, and allowing
@ -343,7 +343,7 @@
<para>Most of the tasks listed in the previous sections require
either a considerable investment of time or an in-depth knowledge
of the FreeBSD kernel (or both). However, there are also many
of the FreeBSD kernel (or both). However, there are also many
useful tasks which are suitable for &quot;weekend hackers&quot;,
or people without programming skills.</para>
@ -359,16 +359,16 @@
</listitem>
<listitem>
<para>Read the <email>freebsd-bugs</email> mailing list. There might be a
<para>Read the <email>freebsd-bugs</email> mailing list. There might be a
problem you can comment constructively on or with patches
you can test. Or you could even try to fix one of the
you can test. Or you could even try to fix one of the
problems yourself.</para>
</listitem>
<listitem>
<para>Read through the FAQ and Handbook periodically. If
<para>Read through the FAQ and Handbook periodically. If
anything is badly explained, out of date or even just
completely wrong, let us know. Even better, send us a fix
completely wrong, let us know. Even better, send us a fix
(SGML is not difficult to learn, but there is no objection
to ASCII submissions).</para>
</listitem>
@ -376,7 +376,7 @@
<listitem>
<para>Help translate FreeBSD documentation into your native
language (if not already available) &mdash; just send an email to
&a.doc; asking if anyone is working on it. Note that you
&a.doc; asking if anyone is working on it. Note that you
are not committing yourself to translating every single
FreeBSD document by doing this &mdash; in fact, the documentation
most in need of translation is the installation
@ -386,7 +386,7 @@
<listitem>
<para>Read the freebsd-questions mailing list and &ng.misc
occasionally (or even
regularly). It can be very satisfying to share your
regularly). It can be very satisfying to share your
expertise and help people solve their problems; sometimes
you may even learn something new yourself! These forums can
also be a source of ideas for things to work on.</para>
@ -450,24 +450,24 @@
<title>Bug reports and general commentary</title>
<para>An idea or suggestion of <emphasis>general</emphasis>
technical interest should be mailed to the &a.hackers;. Likewise,
technical interest should be mailed to the &a.hackers;. Likewise,
people with an interest in such things (and a tolerance for a
<emphasis>high</emphasis> volume of mail!) may subscribe to the
hackers mailing list by sending mail to &a.majordomo;. See
hackers mailing list by sending mail to &a.majordomo;. See
<link linkend="eresources-mail">mailing lists</link> for more
information about this and other mailing lists.</para>
<para>If you find a bug or are submitting a specific change, please
report it using the <citerefentry><refentrytitle>send-pr</refentrytitle><manvolnum>1</manvolnum></citerefentry>program or its
<ulink URL="http://www.freebsd.org/send-pr.html">WEB-based
equivalent</ulink>. Try to fill-in each field of the bug report.
equivalent</ulink>. Try to fill-in each field of the bug report.
Unless they exceed 65KB, include any patches directly in the
report. Consider compressing them and using
<citerefentry><refentrytitle>uuencode</refentrytitle><manvolnum>1</manvolnum></citerefentry> if they exceed 20KB. Upload very large submissions to <ulink url="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/incoming/">ftp.freebsd.org:/pub/FreeBSD/incoming/</ulink>.</para>
report. Consider compressing them and using
<citerefentry><refentrytitle>uuencode</refentrytitle><manvolnum>1</manvolnum></citerefentry> if they exceed 20KB. Upload very large submissions to <ulink url="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/incoming/">ftp.freebsd.org:/pub/FreeBSD/incoming/</ulink>.</para>
<para>After filing a report, you should receive confirmation along
with a tracking number. Keep this tracking number so that you can
update us with details about the problem by sending mail to <email>bug-followup@FreeBSD.ORG</email>. Use the number as the message subject, e.g. <literal>"Re: kern/3377"</literal>. Additional information for any bug report should be submitted this way.</para>
with a tracking number. Keep this tracking number so that you can
update us with details about the problem by sending mail to <email>bug-followup@FreeBSD.ORG</email>. Use the number as the message subject, e.g. <literal>"Re: kern/3377"</literal>. Additional information for any bug report should be submitted this way.</para>
<para>If you do not receive confirmation in a timely fashion (3 days
to a week, depending on your email connection) or are, for some
@ -480,7 +480,7 @@
<sect2>
<title>Changes to the documentation</title>
<para>Changes to the documentation are overseen by the &a.doc;. Send
<para>Changes to the documentation are overseen by the &a.doc;. Send
submissions and changes (even small ones are welcome!) using
<command>send-pr</command> as described in
<link linkend="contrib-general">Bug Reports and General
@ -503,16 +503,16 @@
<para>Working from older sources unfortunately means that your
changes may sometimes be too obsolete or too divergent for easy
re-integration into FreeBSD. Chances of this can be minimized
re-integration into FreeBSD. Chances of this can be minimized
somewhat by subscribing to the &a.announce; and the &a.current;
lists, where discussions on the current state of the system take
place.</para>
<para>Assuming that you can manage to secure fairly up-to-date
sources to base your changes on, the next step is to produce a set
of diffs to send to the FreeBSD maintainers. This is done with
of diffs to send to the FreeBSD maintainers. This is done with
the <citerefentry><refentrytitle>diff</refentrytitle><manvolnum>1</manvolnum></citerefentry> command, with the &ldquo;context diff&rdquo;
form being preferred. For example:</para>
form being preferred. For example:</para>
<para>
<screen>&prompt.user; <userinput>diff -c oldfile newfile</userinput></screen>
@ -525,15 +525,15 @@
would generate such a set of context diffs for
the given source file or directory hierarchy. See the man page
the given source file or directory hierarchy. See the man page
for <citerefentry><refentrytitle>diff</refentrytitle><manvolnum>1</manvolnum></citerefentry> for more details.</para>
<para>Once you have a set of diffs (which you may test with the
<citerefentry><refentrytitle>patch</refentrytitle><manvolnum>1</manvolnum></citerefentry> command), you should submit them for
inclusion with FreeBSD. Use the <citerefentry><refentrytitle>send-pr</refentrytitle><manvolnum>1</manvolnum></citerefentry>
inclusion with FreeBSD. Use the <citerefentry><refentrytitle>send-pr</refentrytitle><manvolnum>1</manvolnum></citerefentry>
program as described in
<link linkend="contrib-general">Bug Reports and General
Commentary</link>. <emphasis>Do not</emphasis> just send the diffs to
Commentary</link>. <emphasis>Do not</emphasis> just send the diffs to
the &a.hackers; or they will get lost! We greatly appreciate your
submission (this is a volunteer project!); because we are busy, we
may not be able to address it immediately, but it will remain in
@ -541,22 +541,22 @@
<para>If you feel it appropriate (e.g. you have added, deleted, or
renamed files), bundle your changes into a <command>tar</command> file and run the
<citerefentry><refentrytitle>uuencode</refentrytitle><manvolnum>1</manvolnum></citerefentry> program on it. Shar archives are
<citerefentry><refentrytitle>uuencode</refentrytitle><manvolnum>1</manvolnum></citerefentry> program on it. Shar archives are
also welcome.</para>
<para>If your change is of a potentially sensitive nature, e.g. you
are unsure of copyright issues governing its further distribution
or you are simply not ready to release it without a tighter review
first, then you should send it to &a.core; directly rather than
submitting it with <citerefentry><refentrytitle>send-pr</refentrytitle><manvolnum>1</manvolnum></citerefentry>. The core
submitting it with <citerefentry><refentrytitle>send-pr</refentrytitle><manvolnum>1</manvolnum></citerefentry>. The core
mailing list reaches a much smaller group of people who do much of
the day-to-day work on FreeBSD. Note that this group is also
the day-to-day work on FreeBSD. Note that this group is also
<emphasis>very busy</emphasis> and so you should only send mail to
them where it is truly necessary.</para>
<para>Please refer to <command>man 9 intro</command> and
<command>man 9 style</command> for some information on
coding style. We would appreciate it if you were at least aware
coding style. We would appreciate it if you were at least aware
of this information before submitting code.</para>
</sect2>
@ -571,16 +571,16 @@
URL="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/incoming">ftp://ftp.FreeBSD.ORG/pub/FreeBSD/incoming</ulink>.</para>
<para>When working with large amounts of code, the touchy subject of
copyrights also invariably comes up. Acceptable copyrights for
copyrights also invariably comes up. Acceptable copyrights for
code included in FreeBSD are:</para>
<orderedlist>
<listitem>
<para>The BSD copyright. This copyright is most preferred due
<para>The BSD copyright. This copyright is most preferred due
to its &ldquo;no strings attached&rdquo; nature and general
attractiveness to commercial enterprises. Far from
attractiveness to commercial enterprises. Far from
discouraging such commercial use, the FreeBSD Project
actively encourages such participation by commercial
interests who might eventually be inclined to invest
@ -588,13 +588,13 @@
</listitem>
<listitem>
<para>The GNU Public License, or &ldquo;GPL&rdquo;. This license is not
<para>The GNU Public License, or &ldquo;GPL&rdquo;. This license is not
quite as popular with us due to the amount of extra effort
demanded of anyone using the code for commercial purposes,
but given the sheer quantity of GPL'd code we currently
require (compiler, assembler, text formatter, etc) it would
be silly to refuse additional contributions under this
license. Code under the GPL also goes into a different part
license. Code under the GPL also goes into a different part
of the tree, that being <filename>/sys/gnu</filename> or
<filename>/usr/src/gnu</filename>, and is therefore easily
identifiable to anyone for whom the GPL presents a
@ -606,7 +606,7 @@
<para>Contributions coming under any other type of copyright must be
carefully reviewed before their inclusion into FreeBSD will be
considered. Contributions for which particularly restrictive
considered. Contributions for which particularly restrictive
commercial copyrights apply are generally rejected, though the
authors are always encouraged to make such changes available
through their own channels.</para>
@ -670,7 +670,7 @@ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
<para>FreeBSD, Inc. was founded in early 1995 by &a.jkh; and
&a.dg; with the goal of furthering the aims of the FreeBSD
Project and giving it a minimal corporate presence. Any and all
Project and giving it a minimal corporate presence. Any and all
funds donated (as well as any profits that may eventually be
realized by FreeBSD, Inc.) will be used exclusively to further
the project's goals.</para>
@ -709,7 +709,7 @@ box can be opened)</para>
<para>If you do not wish to be listed in our <link
linkend="donors">donors</link> section, please specify this
when making your donation. Thanks!</para>
when making your donation. Thanks!</para>
</sect3>
@ -731,9 +731,9 @@ box can be opened)</para>
<listitem>
<para>Hardware for which ongoing compliance testing is
desired. We are currently trying to put together a testing
desired. We are currently trying to put together a testing
lab of all components that FreeBSD supports so that proper
regression testing can be done with each new release. We
regression testing can be done with each new release. We
are still lacking many important pieces (network cards,
motherboards, etc) and if you would like to make such a
donation, please contact &a.dg; for information on
@ -742,7 +742,7 @@ box can be opened)</para>
<listitem>
<para>Hardware currently unsupported by FreeBSD for which
you would like to see such support added. Please contact
you would like to see such support added. Please contact
the &a.core; before sending such items as we will need to
find a developer willing to take on the task before we can
accept delivery of new hardware.</para>
@ -756,7 +756,7 @@ box can be opened)</para>
<sect3>
<title>Donating Internet access</title>
<para>We can always use new mirror sites for FTP, WWW or <command>cvsup</command>. If
<para>We can always use new mirror sites for FTP, WWW or <command>cvsup</command>. If
you would like to be such a mirror, please contact the FreeBSD project
administrators <email>admin@FreeBSD.ORG</email> for more information.</para>
@ -965,7 +965,7 @@ box can be opened)</para>
</listitem>
<listitem>
<para>Ernst Winter <email>ewinter@lobo.muc.de</email> contributed a 2.88 MB floppy drive to the project. This will hopefully increase the pressure for rewriting the floppy disk driver. <!-- smiley -->;-)</para>
<para>Ernst Winter <email>ewinter@lobo.muc.de</email> contributed a 2.88 MB floppy drive to the project. This will hopefully increase the pressure for rewriting the floppy disk driver. <!-- smiley -->;-)</para>
</listitem>
<listitem>
@ -973,7 +973,7 @@ box can be opened)</para>
Technologies</ulink> sent one each of their DC-390,
DC-390U and DC-390F FAST and ULTRA SCSI host adapter
cards for regression testing of the NCR and AMD drivers
with their cards. They are also to be applauded for
with their cards. They are also to be applauded for
making driver sources for free operating systems
available from their FTP server <ulink
URL="ftp://ftp.tekram.com/scsi/FreeBSD">ftp://ftp.tekram.com/scsi/FreeBSD</ulink>.</para>
@ -1011,12 +1011,12 @@ box can be opened)</para>
CDROM</ulink> has donated almost more than we can say
(see the
<link linkend="history">history</link> document for
more details). In particular, we would like to thank
more details). In particular, we would like to thank
them for the original hardware used for
<hostid role="fqdn">freefall.FreeBSD.ORG</hostid>, our primary
development machine, and for
<hostid role="fqdn">thud.FreeBSD.ORG</hostid>, a testing and
build box. We are also indebted to them for funding
build box. We are also indebted to them for funding
various contributors over the years and providing us
with unrestricted use of their T1 connection to the
Internet.</para>
@ -1110,7 +1110,7 @@ box can be opened)</para>
<para>This software was originally derived from William F. Jolitz's
386BSD release 0.1, though almost none of the original 386BSD
specific code remains. This software has been essentially
specific code remains. This software has been essentially
re-implemented from the 4.4BSD-Lite release provided by the Computer
Science Research Group (CSRG) at the University of California,
Berkeley and associated academic contributors.</para>

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

File diff suppressed because it is too large Load diff

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

@ -4,84 +4,84 @@
<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
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
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
<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
disk was found. Continuing with our example, the newly added drive will be
<filename>sd1</filename> and we want to mount it on
<filename>/1</filename>. (if you are adding an IDE drive substitute
<filename>/1</filename>. (if you are adding an IDE drive substitute
<filename>wd</filename> for <filename>sd</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
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
<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
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
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/sd1s1e</filename>. This is read as: SCSI disk, unit number
<filename>/dev/sd1s1e</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
<filename>e</filename> BSD partition. In the dedicated case, the drive
will be added simply as <filename>/dev/sd1e</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
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
<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>Partition</literal> item. Next you should be presented with a
list of hard drives installed in your system. If you do not see
<literal>sd1</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>sd1</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
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>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
<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
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>
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
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
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
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
@ -101,9 +101,9 @@
<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
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
will be done by them. IBM's OS/2 however, will
&ldquo;appropriate&rdquo; any partition it finds which it doesn't
understand.</para>

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

@ -4,15 +4,15 @@
<para><emphasis>Contributed by &a.jkh;.</emphasis></para>
<para>The rapid pace of FreeBSD progress makes print media impractical
as a means of following the latest developments. Electronic resources
as a means of following the latest developments. Electronic resources
are the best, if not often the only, way stay informed of the latest
advances. Since FreeBSD is a volunteer effort, the user community
advances. Since FreeBSD is a volunteer effort, the user community
itself also generally serves as a &ldquo;technical support department&rdquo; of
sorts, with electronic mail and USENET news being the most effective
way of reaching that community.</para>
<para>The most important points of contact with the FreeBSD user
community are outlined below. If you are aware of other resources not
community are outlined below. If you are aware of other resources not
mentioned here, please send them to the &a.doc;so that they may also
be included.</para>
@ -23,14 +23,14 @@
<para>Though many of the FreeBSD development members read USENET, we
cannot always guarantee that we will get to your questions in a
timely fashion (or at all) if you post them only to one of the
<literal>comp.unix.bsd.freebsd.*</literal> groups. By addressing your questions to the
<literal>comp.unix.bsd.freebsd.*</literal> groups. By addressing your questions to the
appropriate mailing list you will reach both us and a concentrated
FreeBSD audience, invariably assuring a better (or at least faster)
response.</para>
<para>The charters for the various lists are given at the bottom of
this document. <emphasis>Please read the charter before
joining or sending mail to any list</emphasis>. Most of our list
this document. <emphasis>Please read the charter before
joining or sending mail to any list</emphasis>. Most of our list
subscribers now receive many hundreds of FreeBSD related messages
every day, and by setting down charters and rules for proper use we
are striving to keep the signal-to-noise ratio of the lists high.
@ -40,7 +40,7 @@
<para>Archives are kept for all of the mailing lists and can be
searched using the <ulink
URL="http://www.FreeBSD.ORG/search.html">FreeBSD World Wide Web
server</ulink>. The keyword searchable archive offers an
server</ulink>. The keyword searchable archive offers an
excellent way of finding answers to frequently asked questions and
should be consulted before posting a question.</para>
@ -121,7 +121,7 @@
</informaltable>
<para><emphasis>Technical lists:</emphasis> The following
lists are for technical discussion. You should read the charter
lists are for technical discussion. You should read the charter
for each list carefully before joining or sending mail to one as
there are firm guidelines for their use and content.</para>
@ -252,7 +252,7 @@
<para><emphasis>Limited lists:</emphasis> The following
lists require approval from <email>core@FreeBSD.ORG</email> to join,
though anyone is free to send messages to them which fall within
the scope of their charters. It is also a good idea establish a
the scope of their charters. It is also a good idea establish a
presence in the technical lists before asking to join one of these
limited lists.</para>
@ -307,7 +307,7 @@
<para><emphasis>CVS lists:</emphasis> The following lists
are for people interested in seeing the log messages for changes
to various areas of the source tree. They are <emphasis>Read-Only</emphasis> lists and should not have mail
to various areas of the source tree. They are <emphasis>Read-Only</emphasis> lists and should not have mail
sent to them.</para>
<informaltable frame="none">
@ -336,7 +336,7 @@
<para>All mailing lists live on <hostid role="fqdn">FreeBSD.ORG</hostid>, so
to post to a given list you simply mail to
<email><replaceable>listname</replaceable>@FreeBSD.ORG</email>. It will
<email><replaceable>listname</replaceable>@FreeBSD.ORG</email>. It will
then be redistributed to mailing list members world-wide.</para>
<para>To subscribe to a list, send mail to &a.majordomo; and include
@ -344,7 +344,7 @@
<programlisting>
subscribe &lt;listname&gt; [&lt;optional address&gt;]</programlisting>
in the body of your message. For example, to
in the body of your message. For example, to
subscribe yourself to <literal>freebsd-announce</literal>, you'd do:</para>
@ -368,7 +368,7 @@ subscribe freebsd-announce local-announce@somesite.com
<para>Finally, it is also possible to unsubscribe
yourself from a list, get a list of other list members or see the
list of mailing lists again by sending other types of control
messages to majordomo. For a complete list of available commands,
messages to majordomo. For a complete list of available commands,
do this:</para>
@ -407,9 +407,9 @@ help
<para>The topic of any posting should adhere to the basic
charter of the list it is posted to, e.g. if the list is
about technical issues then your posting should contain
technical discussion. Ongoing irrelevant chatter or flaming
technical discussion. Ongoing irrelevant chatter or flaming
only detracts from the value of the mailing list for
everyone on it and will not be tolerated. For free-form
everyone on it and will not be tolerated. For free-form
discussion on no particular topic, the freebsd-chat <email>freebsd-chat@freebsd.org</email>
mailing list is freely available and should be used
instead.</para>
@ -418,13 +418,13 @@ help
<listitem>
<para>No posting should be made to more than 2 mailing lists,
and only to 2 when a clear and obvious need to post to both
lists exists. For most lists, there is already a great deal
lists exists. For most lists, there is already a great deal
of subscriber overlap and except for the most esoteric mixes
(say "-stable &amp; -scsi"), there really is no reason to
post to more than one list at a time. If a message is sent
post to more than one list at a time. If a message is sent
to you in such a way that multiple mailing lists appear on
the Cc line then the cc line should also be trimmed before
sending it out again. <emphasis>You are <emphasis>still</emphasis> responsible for your own
sending it out again. <emphasis>You are <emphasis>still</emphasis> responsible for your own
cross-postings, no matter who the originator might have
been.</emphasis></para>
</listitem>
@ -432,10 +432,10 @@ help
<listitem>
<para>Personal attacks and profanity (in the context of an
argument) are not allowed, and that includes users and
developers alike. Gross breaches of netiquette, like
developers alike. Gross breaches of netiquette, like
excerpting or reposting private mail when permission to do
so was not and would not be forthcoming, are frowned upon
but not specifically enforced. <emphasis>However</emphasis>, there are also very few cases
but not specifically enforced. <emphasis>However</emphasis>, there are also very few cases
where such content would fit within the charter of a list
and it would therefore probably rate a warning (or ban) on
that basis alone.</para>
@ -470,7 +470,7 @@ help
<para>This list is purely for discussion of <hostid role="domainname">freebsd.org</hostid>
related issues and to report problems or abuse of project
resources. It is a closed list, though anyone may report
resources. It is a closed list, though anyone may report
a problem (with our systems!) to it.</para>
</listitem>
</varlistentry>
@ -484,8 +484,8 @@ help
<para>This is the mailing list for people interested only
in occasional announcements of significant FreeBSD events.
This includes announcements about snapshots and other
releases. It contains announcements of new FreeBSD
capabilities. It may contain calls for volunteers etc.
releases. It contains announcements of new FreeBSD
capabilities. It may contain calls for volunteers etc.
This is a low volume, strictly moderated mailing
list.</para>
</listitem>
@ -498,10 +498,10 @@ help
discussions</emphasis></para>
<para>This is a moderated list for discussion of FreeBSD
architecture. Messages will mostly be kept technical in
architecture. Messages will mostly be kept technical in
nature, with (rare) exceptions for other messages the
moderator deems need to reach all the subscribers of the
list. Examples of suitable topics;</para>
list. Examples of suitable topics;</para>
<itemizedlist>
<listitem>
@ -527,7 +527,7 @@ help
<para>The moderator reserves the right to do minor editing
(spell-checking, grammar correction, trimming) of messages
that are posted to the list. The volume of the list will be
that are posted to the list. The volume of the list will be
kept low, which may involve having to delay topics until an
active discussion has been resolved.</para>
</listitem>
@ -555,11 +555,11 @@ help
<para>This list contains the
overflow from the other lists about non-technical, social
information. It includes discussion about whether Jordan
information. It includes discussion about whether Jordan
looks like a toon ferret or not, whether or not to type in
capitals, who is drinking too much coffee, where the best
beer is brewed, who is brewing beer in their basement, and
so on. Occasional announcements of important events (such
so on. Occasional announcements of important events (such
as upcoming parties, weddings, births, new jobs, etc) can
be made to the technical lists, but the follow ups should
be directed to this -chat list.</para>
@ -572,7 +572,7 @@ help
<para><emphasis>FreeBSD core team</emphasis></para>
<para>This is an internal mailing list for use by the core
members. Messages can be sent to it when a serious
members. Messages can be sent to it when a serious
FreeBSD-related matter requires arbitration or high-level
scrutiny.</para>
</listitem>
@ -585,11 +585,11 @@ help
FreeBSD-current</emphasis></para>
<para>This is the
mailing list for users of freebsd-current. It includes
mailing list for users of freebsd-current. It includes
warnings about new features coming out in -current that
will affect the users, and instructions on steps that must
be taken to remain -current. Anyone running &ldquo;current&rdquo; must
subscribe to this list. This is a technical mailing list
be taken to remain -current. Anyone running &ldquo;current&rdquo; must
subscribe to this list. This is a technical mailing list
for which strictly technical content is expected.</para>
</listitem>
</varlistentry>
@ -601,10 +601,10 @@ help
FreeBSD-current</emphasis></para>
<para>This is the
digest version of the freebsd-current mailing list. The
digest version of the freebsd-current mailing list. The
digest consists of all messages sent to freebsd-current
bundled together and mailed out as a single message. The
average digest size is about 40kB. This list is <emphasis>Read-Only</emphasis> and should not be posted
bundled together and mailed out as a single message. The
average digest size is about 40kB. This list is <emphasis>Read-Only</emphasis> and should not be posted
to.</para>
</listitem>
</varlistentry>
@ -616,9 +616,9 @@ help
<para>This mailing list is for the discussion of issues and
projects related to the creation of documenation for
FreeBSD. The members of this mailing list are collectively
FreeBSD. The members of this mailing list are collectively
referred to as &ldquo;The FreeBSD Documentation
Project&rdquo;. It is an open list; feel free to join and
Project&rdquo;. It is an open list; feel free to join and
contribute!</para>
</listitem>
</varlistentry>
@ -628,7 +628,7 @@ help
<listitem>
<para><emphasis>Filesystems</emphasis></para>
<para>Discussions concerning FreeBSD filesystems. This is a
<para>Discussions concerning FreeBSD filesystems. This is a
technical mailing list for which strictly technical
content is expected.</para>
</listitem>
@ -662,11 +662,11 @@ help
<para><emphasis>Technical discussions</emphasis></para>
<para>This is a forum for technical discussions related to
FreeBSD. This is the primary technical mailing list. It
FreeBSD. This is the primary technical mailing list. It
is for individuals actively working on FreeBSD, to bring
up problems or discuss alternative solutions. Individuals
up problems or discuss alternative solutions. Individuals
interested in following the technical discussion are also
welcome. This is a technical mailing list for which
welcome. This is a technical mailing list for which
strictly technical content is expected.</para>
</listitem>
</varlistentry>
@ -677,9 +677,9 @@ help
<para><emphasis>Technical discussions</emphasis></para>
<para>This is the digest version of the freebsd-hackers
mailing list. The digest consists of all messages sent to
mailing list. The digest consists of all messages sent to
freebsd-hackers bundled together and mailed out as a
single message. The average digest size is about 40kB.
single message. The average digest size is about 40kB.
This list is <emphasis>Read-Only</emphasis> and
should not be posted to.</para>
</listitem>
@ -717,7 +717,7 @@ help
<para>This mailing list is
for discussing topics relevant to Internet Service
Providers (ISPs) using FreeBSD. This is a technical
Providers (ISPs) using FreeBSD. This is a technical
mailing list for which strictly technical content is
expected.</para>
</listitem>
@ -735,7 +735,7 @@ help
and asking for help elsewhere, how to use mailing lists and
which lists to use, general chat, making mistakes, boasting,
sharing ideas, stories, moral (but not technical) support, and
taking an active part in the FreeBSD community. We take our
taking an active part in the FreeBSD community. We take our
problems and support questions to freebsd-questions, and use
freebsd-newbies to meet others who are doing the same things
that we do as newbies.</para>
@ -750,7 +750,7 @@ help
<para>Cross-platform freebsd
issues, general discussion and proposals for non-Intel
FreeBSD ports. This is a technical mailing list for which
FreeBSD ports. This is a technical mailing list for which
strictly technical content is expected.</para>
</listitem>
</varlistentry>
@ -764,7 +764,7 @@ help
<para>Discussions concerning FreeBSD's &ldquo;ports collection&rdquo;
(<filename>/usr/ports</filename>), proposed ports, modifications to ports
collection infrastructure and general coordination
efforts. This is a technical mailing list for which
efforts. This is a technical mailing list for which
strictly technical content is expected.</para>
</listitem>
</varlistentry>
@ -775,7 +775,7 @@ help
<para><emphasis>User questions</emphasis></para>
<para>This
is the mailing list for questions about FreeBSD. You
is the mailing list for questions about FreeBSD. You
should not send &ldquo;how to&rdquo; questions to the technical lists
unless you consider the question to be pretty
technical.</para>
@ -789,9 +789,9 @@ help
<para>This
is the digest version of the freebsd-questions mailing
list. The digest consists of all messages sent to
list. The digest consists of all messages sent to
freebsd-questions bundled together and mailed out as a
single message. The average digest size is about
single message. The average digest size is about
40kB.</para>
</listitem>
</varlistentry>
@ -803,7 +803,7 @@ help
<para>This
is the mailing list for people working on the scsi
subsystem for FreeBSD. This is a technical mailing list
subsystem for FreeBSD. This is a technical mailing list
for which strictly technical content is expected.</para>
</listitem>
</varlistentry>
@ -814,7 +814,7 @@ help
<para><emphasis>Security issues</emphasis></para>
<para>FreeBSD computer security issues (DES, Kerberos, known
security holes and fixes, etc). This is a technical
security holes and fixes, etc). This is a technical
mailing list for which strictly technical content is
expected.</para>
</listitem>
@ -825,7 +825,7 @@ help
<listitem>
<para><emphasis>Security Notifications</emphasis><!-- <br>
--> Notifications of FreeBSD security problems and fixes.
This is not a discussion list. The discussion list is
This is not a discussion list. The discussion list is
FreeBSD-security.</para>
</listitem>
</varlistentry>
@ -835,7 +835,7 @@ help
<listitem>
<para>This list discusses topics related to unsually small and
embedded FreeBSD installations. This is a technical mailing
embedded FreeBSD installations. This is a technical mailing
list for which strictly technical content is expected.</para>
</listitem>
</varlistentry>
@ -847,11 +847,11 @@ help
FreeBSD-stable</emphasis></para>
<para>This is the
mailing list for users of freebsd-stable. It includes
mailing list for users of freebsd-stable. It includes
warnings about new features coming out in -stable that
will affect the users, and instructions on steps that must
be taken to remain -stable. Anyone running &ldquo;stable&rdquo;
should subscribe to this list. This is a technical mailing
be taken to remain -stable. Anyone running &ldquo;stable&rdquo;
should subscribe to this list. This is a technical mailing
list for which strictly technical content is
expected.</para>
</listitem>
@ -866,9 +866,9 @@ help
<para>This is the mailing list for the coordinators from
each of the local area Users Groups to discuss matters
with each other and a designated individual from the Core
Team. This mail list should be limited to meeting
Team. This mail list should be limited to meeting
synopsis and coordination of projects that span User
Groups. It is a closed list.</para>
Groups. It is a closed list.</para>
</listitem>
</varlistentry>
</variablelist>
@ -882,7 +882,7 @@ help
<para>In addition to two FreeBSD specific newsgroups, there are many
others in which FreeBSD is discussed or are otherwise relevant to
FreeBSD users. <ulink
FreeBSD users. <ulink
URL="http://minnie.cs.adfa.oz.au/BSD-info/bsdnews_search.html">Keyword searchable archives</ulink> are available for some of these newsgroups from courtesy of Warren Toomey <email>wkt@cs.adfa.oz.au</email>.</para>

12
en/handbook/handbook.sgml
View file

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

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

File diff suppressed because it is too large Load diff

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

@ -2,18 +2,18 @@
<title>Installing FreeBSD</title>
<para>So, you would like to try out FreeBSD on your system? This section
is a quick-start guide for what you need to do. FreeBSD can be
is a quick-start guide for what you need to do. FreeBSD can be
installed from a variety of media including CD-ROM, floppy disk,
magnetic tape, an MS-DOS partition and, if you have a network
connection, via anonymous ftp or NFS.</para>
<para>Regardless of the installation media you choose, you can get
started by creating the <emphasis>installation
disks</emphasis> as described below. Booting your computer into the
disks</emphasis> as described below. Booting your computer into the
FreeBSD installer, even if you aren't planning on installing FreeBSD
right away, will provide important information about compatibility
between FreeBSD and your hardware which may, in turn, dictate which
installation options are even possible. It can also provide early
installation options are even possible. It can also provide early
clues to any compatibility problems which could prevent FreeBSD
running on your system at all.</para>
@ -35,9 +35,9 @@
<step>
<para>Review the <link linkend="install-hw">supported
configurations</link> section of this installation guide to be sure
that your hardware is supported by FreeBSD. It may be helpful
that your hardware is supported by FreeBSD. It may be helpful
to make a list of any special cards you have installed, such as
SCSI controllers, Ethernet adapters or sound cards. This list
SCSI controllers, Ethernet adapters or sound cards. This list
should include relevant configuration parameters such as
interrupts (IRQ) and IO port addresses.</para>
</step>
@ -58,7 +58,7 @@
<listitem>
<para>If you're running DOS and have the proper drivers to
access your CD, run the install.bat script provided on the
CD. This will attempt to boot into the FreeBSD
CD. This will attempt to boot into the FreeBSD
installation straight from DOS.</para>
<note>
@ -130,16 +130,16 @@
<step>
<para>With the <filename>kern.flp</filename> in the <devicename>A:</devicename> drive, reboot your
computer. The next request you should get is for the
computer. The next request you should get is for the
<filename>mfsroot.flp</filename> floppy, after which the
installation will proceed normally.</para>
<para>If you do <emphasis>not</emphasis> type anything at the boot
prompt which appears during this process, FreeBSD will
automatically boot with its default
configuration after a delay of about five seconds. As FreeBSD
configuration after a delay of about five seconds. As FreeBSD
boots, it probes your computer to determine what hardware is
installed. The results of this probing is displayed on the
installed. The results of this probing is displayed on the
screen.</para>
</step>
@ -153,7 +153,7 @@
<para><emphasis>If something goes wrong&hellip;</emphasis></para>
<para>Due to limitations of the PC architecture, it is impossible for
probing to be 100 percent reliable. In the event that your hardware
probing to be 100 percent reliable. In the event that your hardware
is incorrectly identified, or that the probing causes your computer to
lock up, first check the
<link linkend="install-hw">supported configurations</link>
@ -163,24 +163,24 @@
<para>If your hardware is supported, reset the computer and when the
visual kernel configuration choice is presented, take it.
This puts FreeBSD into a configuration mode
where you can supply hints about your hardware. The FreeBSD kernel on
where you can supply hints about your hardware. The FreeBSD kernel on
the installation disk is configured assuming that most hardware
devices are in their factory default configuration in terms of IRQs,
IO addresses and DMA channels. If your hardware has been
IO addresses and DMA channels. If your hardware has been
reconfigured, you will most likely need to use the configuration
editor to tell FreeBSD where things are.</para>
<para>It is also possible that a probe for a device not present will
cause a later probe for another device that is present to fail. In
cause a later probe for another device that is present to fail. In
that case, the probes for the conflicting driver(s) should be
disabled.</para>
<warning>
<para>Do not disable any device you will need during installation, such
as your screen (<devicename>sc0</devicename>). If the installation
as your screen (<devicename>sc0</devicename>). If the installation
wedges or fails mysteriously after leaving the configuration editor,
you have probably removed or changed something that you should not
have. Simply reboot and try again.</para>
have. Simply reboot and try again.</para>
</warning>
<para>In the configuration mode, you can:</para>
@ -211,8 +211,8 @@
<para>After FreeBSD has been installed, changes made in the
configuration mode will be permanent so you do not have to reconfigure
every time you boot. Even so, it is likely that you will want to
build a custom kernel to optimize the performance of your system. See
every time you boot. Even so, it is likely that you will want to
build a custom kernel to optimize the performance of your system. See
<link linkend="kernelconfig"
>Kernel configuration</link> for more information on creating
custom kernels.</para>
@ -223,7 +223,7 @@
<para>FreeBSD currently runs on a wide variety of ISA, VLB, EISA and
PCI bus based PC's, ranging from 386sx to Pentium class machines
(though the 386sx is not recommended). Support for generic IDE or
(though the 386sx is not recommended). Support for generic IDE or
ESDI drive configurations, various SCSI controller, network and
serial cards is also provided.</para>
@ -232,7 +232,7 @@
recommended minimum.</para>
<para>Following is a list of all disk controllers and Ethernet cards
currently known to work with FreeBSD. Other configurations may very
currently known to work with FreeBSD. Other configurations may very
well work, and we have simply not received any indication of
this.</para>
@ -298,11 +298,11 @@
<para>You cannot boot from the
SoundBlaster cards as they have no on-board BIOS, which is
necessary for mapping the boot device into the system BIOS
I/O vectors. They are perfectly usable for external tapes,
CDROMs, etc, however. The same goes for any other AIC-6x60
based card without a boot ROM. Some systems DO have a boot
I/O vectors. They are perfectly usable for external tapes,
CDROMs, etc, however. The same goes for any other AIC-6x60
based card without a boot ROM. Some systems DO have a boot
ROM, which is generally indicated by some sort of message
when the system is first powered up or reset. Check your
when the system is first powered up or reset. Check your
system/board documentation for more details.</para>
</note>
</listitem>
@ -414,7 +414,7 @@
<listitem>
<para>SMC Elite 16 WD8013 Ethernet interface, and most other
WD8003E, WD8003EBT, WD8003W, WD8013W, WD8003S, WD8003SBT and
WD8013EBT based clones. SMC Elite Ultra and 9432TX based
WD8013EBT based clones. SMC Elite Ultra and 9432TX based
cards are also supported.</para>
</listitem>
@ -581,7 +581,7 @@
<note>
<para>FreeBSD does not currently support
PnP (plug-n-play) features present on some ethernet cards. If
PnP (plug-n-play) features present on some ethernet cards. If
your card has PnP and is giving you problems, try disabling its
PnP features.</para>
</note>
@ -678,7 +678,7 @@
<title>Preparing for the Installation</title>
<para>There are a number of different methods by which FreeBSD can be
installed. The following describes what preparation needs to be
installed. The following describes what preparation needs to be
done for each type.</para>
@ -703,11 +703,11 @@
<para>If you are creating the boot floppies from a UNIX machine, see
<link linkend="install">the beginning of this
guide</link> for examples. of how to create the boot floppies.</para>
guide</link> for examples. of how to create the boot floppies.</para>
<para>Once you have booted from DOS or floppy, you should then be
able to select CDROM as the media type in the Media menu and load
the entire distribution from CDROM. No other types of
the entire distribution from CDROM. No other types of
installation media should be required.</para>
<para>After your system is fully installed and you have rebooted
@ -715,12 +715,12 @@
<command>mount /cdrom</command></para>
<para>Before removing the CD again, also note that it is necessary
to first type: <command>umount /cdrom</command>. Do not just
to first type: <command>umount /cdrom</command>. Do not just
remove it from the drive!</para>
<note>
<para>Before invoking the installation, be sure that the CDROM is
in the drive so that the install probe can find it. This is
in the drive so that the install probe can find it. This is
also true if you wish the CDROM to be added to the default
system configuration automatically during the install (whether
or not you actually use it as the installation media).</para>
@ -728,7 +728,7 @@
<para>Finally, if you would like people to be able to FTP install
FreeBSD directly from the CDROM in your machine, you will find it
quite easy. After the machine is fully installed, you simply need
quite easy. After the machine is fully installed, you simply need
to add the following line to the password file (using the vipw
command):</para>
@ -753,20 +753,20 @@ ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent</programlisting>
<para>You will need, at minimum, as many 1.44MB or 1.2MB floppies as
it takes to hold all files in the bin (binary distribution)
directory. If you are preparing these floppies under DOS, then
directory. If you are preparing these floppies under DOS, then
THESE floppies <emphasis>must</emphasis> be formatted using the MS-DOS FORMAT
command. If you are using Windows, use the Windows File Manager
command. If you are using Windows, use the Windows File Manager
format command.</para>
<para>Do <emphasis>not</emphasis> trust Factory Preformatted
floppies! Format them again yourself, just to make sure. Many
floppies! Format them again yourself, just to make sure. Many
problems reported by our users in the past have resulted from the
use of improperly formatted media, which is why I am taking such
special care to mention it here!</para>
<para>If you are creating the floppies from another FreeBSD machine,
a format is still not a bad idea though you do not need to put a
DOS filesystem on each floppy. You can use the <command>disklabel</command> and
DOS filesystem on each floppy. You can use the <command>disklabel</command> and
<command>newfs</command> commands to put a UFS filesystem on them instead, as the
following sequence of commands (for a 3.5" 1.44MB floppy disk)
illustrates:</para>
@ -789,11 +789,11 @@ ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent</programlisting>
system.</para>
<para>After you have formatted the floppies, you will need to copy
the files onto them. The distribution files are split into chunks
the files onto them. The distribution files are split into chunks
conveniently sized so that 5 of them will fit on a conventional
1.44MB floppy. Go through all your floppies, packing as many
1.44MB floppy. Go through all your floppies, packing as many
files as will fit on each one, until you have got all the
distributions you want packed up in this fashion. Each
distributions you want packed up in this fashion. Each
distribution should go into a subdirectory on the floppy, e.g.:
<filename>a:\bin\bin.aa</filename>,
<filename>a:\bin\bin.ab</filename>, and so on.</para>
@ -808,7 +808,7 @@ ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent</programlisting>
<para>To prepare for installation from an MS-DOS partition, copy the
files from the distribution into a directory called
<filename>C:\FREEBSD</filename>. The directory tree structure of
<filename>C:\FREEBSD</filename>. The directory tree structure of
the CDROM must be partially reproduced within this directory so we
suggest using the DOS <command>xcopy</command> command.
For example, to prepare for a minimal installation of FreeBSD:</para>
@ -834,7 +834,7 @@ ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent</programlisting>
<title>Before installing from QIC/SCSI Tape</title>
<para>Installing from tape is probably the easiest method, short of
an on-line install using FTP or a CDROM install. The installation
an on-line install using FTP or a CDROM install. The installation
program expects the files to be simply tar'ed onto the tape, so
after getting all of the files for distribution you are interested
in, simply tar them onto the tape with a command like:</para>
@ -849,7 +849,7 @@ ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent</programlisting>
that you leave enough room in some temporary directory (which you
will be allowed to choose) to accommodate the <emphasis>full</emphasis> contents of the tape you have created.
Due to the non-random access nature of tapes, this method of
installation requires quite a bit of temporary storage. You
installation requires quite a bit of temporary storage. You
should expect to require as much temporary storage as you have
stuff written on tape.</para>
@ -895,28 +895,28 @@ ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent</programlisting>
<para>SLIP support is rather primitive, and limited primarily to
hard-wired links, such as a serial cable running between a laptop
computer and another computer. The link should be hard-wired as
computer and another computer. The link should be hard-wired as
the SLIP installation does not currently offer a dialing
capability; that facility is provided with the PPP utility, which
should be used in preference to SLIP whenever possible.</para>
<para>If you are using a modem, then PPP is almost certainly your
only choice. Make sure that you have your service provider's
only choice. Make sure that you have your service provider's
information handy as you will need to know it fairly soon in the
installation process. You will need to know how to dial your ISP
installation process. You will need to know how to dial your ISP
using the &ldquo;AT commands&rdquo; specific to your modem, as the PPP
dialer provides only a very simple terminal emulator. If you're
dialer provides only a very simple terminal emulator. If you're
using PAP or CHAP, you'll need to type the necessary <command>set
authname</command> and <command>set authkey</command> commands before typing <command>term</command>.
Refer to the user-ppp <link linkend="userppp">handbook</link>
and <ulink URL="../FAQ/userppp.html">FAQ</ulink> entries for
further information. If you have problems, logging can be
further information. If you have problems, logging can be
directed to the screen using the command <command>set
log local ...</command>.</para>
<para>If a hard-wired connection to another FreeBSD (2.0R or later)
machine is available, you might also consider installing over a
&ldquo;laplink&rdquo; parallel port cable. The data rate over the parallel
&ldquo;laplink&rdquo; parallel port cable. The data rate over the parallel
port is much higher than what is typically possible over a serial
line (up to 50k/sec), thus resulting in a quicker
installation.</para>
@ -926,7 +926,7 @@ ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent</programlisting>
common PC ethernet cards, a table of supported cards (and their
required settings) is provided in <link linkend="install-hw"
>Supported
Hardware</link>. If you are using one of the supported PCMCIA
Hardware</link>. If you are using one of the supported PCMCIA
ethernet cards, also be sure that it is plugged in
<emphasis>before</emphasis> the laptop is powered on! FreeBSD
does not, unfortunately, currently support hot insertion of PCMCIA
@ -934,12 +934,12 @@ ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent</programlisting>
<para>You will also need to know your IP address on the network, the
netmask value for your address class, and the name of your
machine. Your system administrator can tell you which values to
use for your particular network setup. If you will be referring
machine. Your system administrator can tell you which values to
use for your particular network setup. If you will be referring
to other hosts by name rather than IP address, you will also need
a name server and possibly the address of a gateway (if you are
using PPP, it is your provider's IP address) to use in talking to
it. If you do not know the answers to all or most of these
it. If you do not know the answers to all or most of these
questions, then you should really probably talk to your system
administrator <emphasis>first</emphasis> before trying this type
of installation.</para>
@ -974,8 +974,8 @@ ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent</programlisting>
<filename>/usr/archive/stuff</filename>.</para>
<para>In FreeBSD's <filename>/etc/exports</filename> file, this is
controlled by the <option>-alldirs</option> option. Other
NFS servers may have different conventions. If you are getting
controlled by the <option>-alldirs</option> option. Other
NFS servers may have different conventions. If you are getting
<errortype>Permission Denied</errortype> messages from the server then it is likely
that you do not have this enabled properly.</para>
@ -985,14 +985,14 @@ ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent</programlisting>
<title>Preparing for FTP Installation</title>
<para>FTP installation may be done from any mirror site containing
a reasonably up-to-date version of FreeBSD &rel.current;. A
a reasonably up-to-date version of FreeBSD &rel.current;. A
full menu of reasonable choices from almost anywhere in the
world is provided by the FTP site menu.</para>
<para>If you are installing from some other FTP site not listed in
this menu, or you are having troubles getting your name server
configured properly, you can also specify your own URL by
selecting the &ldquo;Other&rdquo; choice in that menu. A URL can also be
selecting the &ldquo;Other&rdquo; choice in that menu. A URL can also be
a direct IP address, so the following would work in the absence
of a name server:</para>
@ -1008,7 +1008,7 @@ ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent</programlisting>
<variablelist>
<varlistentry><term>FTP Active</term>
<listitem>
<para>For all FTP transfers, use &ldquo;Active&rdquo; mode. This
<para>For all FTP transfers, use &ldquo;Active&rdquo; mode. This
will not work through firewalls, but will often work
with older ftp servers that do not support passive mode.
If your connection hangs with passive mode (the
@ -1019,7 +1019,7 @@ ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent</programlisting>
<varlistentry><term>FTP Passive</term>
<listitem>
<para>For all FTP transfers, use &ldquo;Passive&rdquo; mode. This
<para>For all FTP transfers, use &ldquo;Passive&rdquo; mode. This
allows the user to pass through firewalls that do not
allow incoming connections on random port
addresses.</para>
@ -1036,13 +1036,13 @@ ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent</programlisting>
<para>For a proxy FTP server, you should usually give name of the
server you really want as a part of the username, after an
@-sign. The proxy server then 'fakes' the real server. An
@-sign. The proxy server then 'fakes' the real server. An
example: Say you want to install from <hostid role="fqdn">ftp.freebsd.org</hostid>, using the
proxy FTP server <hostid role="fqdn">foo.bar.com</hostid>, listening on port 1234.</para>
<para>In this case, you go to the options menu, set the FTP
username to ftp@ftp.freebsd.org, and the password to your e-mail
address. As your installation media, you specify FTP (or
address. As your installation media, you specify FTP (or
passive FTP, if the proxy support it), and the URL
<literal>
@ -1076,10 +1076,10 @@ ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent</programlisting>
<para>The FreeBSD boot floppies contain all the on-line documentation
you should need to be able to navigate through an installation and
if it does not then we would like to know what you found most
confusing. Send your comments to the &a.doc;. It is the objective
confusing. Send your comments to the &a.doc;. It is the objective
of the FreeBSD installation program (sysinstall) to be
self-documenting enough that painful &ldquo;step-by-step&rdquo; guides are no
longer necessary. It may take us a little while to reach that
longer necessary. It may take us a little while to reach that
objective, but that is the objective!</para>
<para>Meanwhile, you may also find the following &ldquo;typical
@ -1091,17 +1091,17 @@ ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent</programlisting>
<listitem>
<para>Boot the <filename>kern.flp</filename> floppy and, when
asked, remove it and insert the
<filename>mfsroot.flp</filename> floppy and hit return.. After a boot sequence which can
<filename>mfsroot.flp</filename> floppy and hit return. After a boot sequence which can
take anywhere from 30 seconds to 3 minutes, depending on your
hardware, you should be presented with a menu of initial
choices. If the <filename>kern.flp</filename> floppy does not boot at all, or the boot
choices. If the <filename>kern.flp</filename> floppy does not boot at all, or the boot
hangs at some stage, go read the Q&amp;A section of the
Hardware Guide for possible causes.</para>
</listitem>
<listitem>
<para>Press F1. You should see some basic usage instructions on
the menu system and general navigation. If you have not used
<para>Press F1. You should see some basic usage instructions on
the menu system and general navigation. If you have not used
this menu system before then <emphasis>please</emphasis> read this thoroughly!</para>
</listitem>
@ -1116,17 +1116,17 @@ ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent</programlisting>
through a typical installation, give you a high degree of
control over each step of the installation or simply whizz
through it (using reasonable defaults when possible) as fast
as possible. If you have never used FreeBSD before then the
as possible. If you have never used FreeBSD before then the
Novice installation method is most recommended.</para>
</listitem>
<listitem>
<para>The final configuration menu choice allows you to further
configure your FreeBSD installation by giving you menu-driven
access to various system defaults. Some items, like
access to various system defaults. Some items, like
networking, may be especially important if you did a
CDROM/Tape/Floppy installation and have not yet configured
your network interfaces (assuming you have any). Properly
your network interfaces (assuming you have any). Properly
configuring such interfaces here will allow FreeBSD to come up
on the network when you first reboot from the hard
disk.</para>
@ -1141,7 +1141,7 @@ ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent</programlisting>
<title>MS-DOS User's Questions and Answers</title>
<para>Many FreeBSD users wish to install FreeBSD on PCs inhabited by
MS-DOS. Here are some commonly asked questions about installing
MS-DOS. Here are some commonly asked questions about installing
FreeBSD on such systems.</para>
<para><emphasis>Help! I have no space! Do I need to delete
@ -1154,11 +1154,11 @@ ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent</programlisting>
<para>FIPS allows you to split an existing MS-DOS partition into two
pieces, preserving the original partition and allowing you to
install onto the second free piece. You first defragment your
install onto the second free piece. You first defragment your
MS-DOS partition, using the DOS 6.xx DEFRAG utility or the Norton
Disk tools, then run FIPS. It will prompt you for the rest of the
information it needs. Afterwards, you can reboot and install
FreeBSD on the new free slice. See the
Disk tools, then run FIPS. It will prompt you for the rest of the
information it needs. Afterwards, you can reboot and install
FreeBSD on the new free slice. See the
<emphasis>Distributions</emphasis> menu for an estimation of how
much free space you will need for the kind of installation you
want.</para>
@ -1166,11 +1166,11 @@ ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent</programlisting>
<para><emphasis>Can I use compressed MS-DOS filesystems from
FreeBSD?</emphasis></para>
<para>No. If you are using a utility such as Stacker(tm) or
<para>No. If you are using a utility such as Stacker(tm) or
DoubleSpace(tm), FreeBSD will only be able to use whatever portion
of the filesystem you leave uncompressed. The rest of the
of the filesystem you leave uncompressed. The rest of the
filesystem will show up as one large file (the stacked/dblspaced
file!). <emphasis>Do not remove that file!</emphasis> You
file!). <emphasis>Do not remove that file!</emphasis> You
will probably regret it greatly!</para>
<para>It is probably better to create another uncompressed MS-DOS
@ -1180,11 +1180,11 @@ ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent</programlisting>
<para><emphasis>Can I mount my MS-DOS extended
partitions?</emphasis></para>
<para>Yes. DOS extended partitions are mapped in at the end of the
other &ldquo;slices&rdquo; in FreeBSD, e.g. your <devicename>D:</devicename> drive might be <filename>/dev/sd0s5</filename>,
your <devicename>E:</devicename> drive <filename>/dev/sd0s6</filename>, and so on. This example assumes, of
course, that your extended partition is on SCSI drive 0. For IDE
drives, substitute <filename>wd</filename> for <filename>sd</filename> appropriately. You otherwise
<para>Yes. DOS extended partitions are mapped in at the end of the
other &ldquo;slices&rdquo; in FreeBSD, e.g. your <devicename>D:</devicename> drive might be <filename>/dev/sd0s5</filename>,
your <devicename>E:</devicename> drive <filename>/dev/sd0s6</filename>, and so on. This example assumes, of
course, that your extended partition is on SCSI drive 0. For IDE
drives, substitute <filename>wd</filename> for <filename>sd</filename> appropriately. You otherwise
mount extended partitions exactly like you would mount any other DOS
drive, e.g.:</para>

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

@ -11,7 +11,7 @@
<para>Booting FreeBSD is essentially a three step process: load the
kernel, determine the root filesystem and initialize user-land
things. This leads to some interesting possibilities shown
things. This leads to some interesting possibilities shown
below.</para>
@ -26,7 +26,7 @@
<variablelist>
<varlistentry><term>Biosboot</term>
<listitem>
<para>Biosboot is our &ldquo;bootblocks&rdquo;. It consists of two
<para>Biosboot is our &ldquo;bootblocks&rdquo;. It consists of two
files which will be installed in the first 8Kbytes of the
floppy or hard-disk slice to be booted from.</para>
@ -38,13 +38,13 @@
<varlistentry><term>Dosboot</term>
<listitem>
<para>Dosboot was written by DI. Christian Gusenbauer, and
<para>Dosboot was written by DI. Christian Gusenbauer, and
is unfortunately at this time one of the few pieces of
code that will not compile under FreeBSD itself because it
is written for Microsoft compilers.</para>
<para>Dosboot will boot the kernel from a MS-DOS file or
from a FreeBSD filesystem partition on the disk. It
from a FreeBSD filesystem partition on the disk. It
attempts to negotiate with the various and strange kinds
of memory manglers that lurk in high memory on MS/DOS
systems and usually wins them for its case.</para>
@ -80,7 +80,7 @@
<variablelist>
<varlistentry><term>UFS</term>
<listitem>
<para>This is the most normal type of root filesystem. It
<para>This is the most normal type of root filesystem. It
can reside on a floppy or on hard disk.</para>
</listitem>
</varlistentry>
@ -99,7 +99,7 @@
<listitem>
<para>This is actually a UFS filesystem which has been
compiled into the kernel. That means that the kernel does
compiled into the kernel. That means that the kernel does
not really need any hard disks, floppies or other hardware
to function.</para>
</listitem>
@ -137,8 +137,8 @@
<command>/sbin/init</command>, as long as you keep in mind
that:</para>
<para>there is no stdin/out/err unless you open it yourself. If you
exit, the machine panics. Signal handling is special for
<para>there is no stdin/out/err unless you open it yourself. If you
exit, the machine panics. Signal handling is special for
<literal>pid == 1</literal>.</para>
<para>An example of this is the
@ -259,16 +259,16 @@
<para>It then loads the first 15 sectors at <literal>0x10000</literal>
(segment <makevar>BOOTSEG</makevar> in the biosboot Makefile), and sets up the stack to
work below <literal>0x1fff0</literal>. After this, it jumps to the
entry of boot2 within that code. I.e., it jumps over itself and the
work below <literal>0x1fff0</literal>. After this, it jumps to the
entry of boot2 within that code. I.e., it jumps over itself and the
(dummy) partition table, and it is going to adjust the %cs
selector&mdash;we are still in 16-bit mode there.</para>
<para>boot2 asks for the boot file, and examines the
<filename>a.out</filename> header. It masks the file entry point
<filename>a.out</filename> header. It masks the file entry point
(usually <literal>0xf0100000</literal>) by
<literal>0x00ffffff</literal>, and loads the file there. Hence the
usual load point is 1 MB (<literal>0x00100000</literal>). During
<literal>0x00ffffff</literal>, and loads the file there. Hence the
usual load point is 1 MB (<literal>0x00100000</literal>). During
load, the boot code toggles back and forth between real and
protected mode, to use the BIOS in real mode.</para>
@ -276,11 +276,11 @@
<literal>0x18</literal> and <literal>0x20</literal> for
<literal>%cs</literal> and <literal>%ds/%es</literal> in
protected mode, and <literal>0x28</literal> to jump back into real
mode. The kernel is finally started with <literal>%cs</literal> <literal>0x08</literal> and
mode. The kernel is finally started with <literal>%cs</literal> <literal>0x08</literal> and
<literal>%ds/%es/%ss</literal> <literal>0x10</literal>, which
refer to dummy descriptors covering the entire address space.</para>
<para>The kernel will be started at its load point. Since it has been
<para>The kernel will be started at its load point. Since it has been
linked for another (high) address, it will have to execute PIC until
the page table and page directory stuff is setup properly, at which
point paging will be enabled and the kernel will finally run at the
@ -290,7 +290,7 @@
1995.</emphasis></para>
<para>The physical pages immediately following the kernel BSS contain
proc0's page directory, page tables, and upages. Some time later
proc0's page directory, page tables, and upages. Some time later
when the VM system is initialized, the physical memory between
<literal>0x1000-0x9ffff</literal> and the physical memory after the
kernel (text+data+bss+proc0 stuff+other misc) is made available in
@ -303,7 +303,7 @@
<title>DMA: What it Is and How it Works</title>
<para><emphasis>Copyright &copy; 1995,1997 &a.uhclem;, All Rights
Reserved.<!-- <br> --> 10 December 1996. Last Update 8 October
Reserved.<!-- <br> --> 10 December 1996. Last Update 8 October
1997.</emphasis></para>
<para>Direct Memory Access (DMA) is a method of allowing data to be
@ -319,25 +319,25 @@
<para>The PC DMA subsystem is based on the Intel 8237 DMA controller.
The 8237 contains four DMA channels that can be programmed
independently and any one of the channels may be active at any
moment. These channels are numbered 0, 1, 2 and 3. Starting with
moment. These channels are numbered 0, 1, 2 and 3. Starting with
the PC/AT, IBM added a second 8237 chip, and numbered those channels
4, 5, 6 and 7.</para>
<para>The original DMA controller (0, 1, 2 and 3) moves one byte in
each transfer. The second DMA controller (4, 5, 6, and 7) moves
each transfer. The second DMA controller (4, 5, 6, and 7) moves
16-bits from two adjacent memory locations in each transfer, with
the first byte always coming from an even-numbered address. The two
the first byte always coming from an even-numbered address. The two
controllers are identical components and the difference in transfer
size is caused by the way the second controller is wired into the
system.</para>
<para>The 8237 has two electrical signals for each channel, named DRQ
and -DACK. There are additional signals with the names HRQ (Hold
and -DACK. There are additional signals with the names HRQ (Hold
Request), HLDA (Hold Acknowledge), -EOP (End of Process), and the
bus control signals -MEMR (Memory Read), -MEMW (Memory Write), -IOR
(I/O Read), and -IOW (I/O Write).</para>
<para>The 8237 DMA is known as a &ldquo;fly-by&rdquo; DMA controller. This
<para>The 8237 DMA is known as a &ldquo;fly-by&rdquo; DMA controller. This
means that the data being moved from one location to another does
not pass through the DMA chip and is not stored in the DMA chip.
Subsequently, the DMA can only transfer data between an I/O port and
@ -361,24 +361,24 @@
<title>A Sample DMA transfer</title>
<para>Here is an example of the steps that occur to cause and
perform a DMA transfer. In this example, the floppy disk
perform a DMA transfer. In this example, the floppy disk
controller (FDC) has just read a byte from a diskette and wants
the DMA to place it in memory at location 0x00123456. The process
the DMA to place it in memory at location 0x00123456. The process
begins by the FDC asserting the DRQ2 signal (the DRQ line for DMA
channel 2) to alert the DMA controller.</para>
<para>The DMA controller will note that the DRQ2 signal is asserted.
The DMA controller will then make sure that DMA channel 2 has been
programmed and is unmasked (enabled). The DMA controller also
programmed and is unmasked (enabled). The DMA controller also
makes sure that none of the other DMA channels are active or want
to be active and have a higher priority. Once these checks are
to be active and have a higher priority. Once these checks are
complete, the DMA asks the CPU to release the bus so that the DMA
may use the bus. The DMA requests the bus by asserting the HRQ
may use the bus. The DMA requests the bus by asserting the HRQ
signal which goes to the CPU.</para>
<para>The CPU detects the HRQ signal, and will complete executing
the current instruction. Once the processor has reached a state
where it can release the bus, it will. Now all of the signals
the current instruction. Once the processor has reached a state
where it can release the bus, it will. Now all of the signals
normally generated by the CPU (-MEMR, -MEMW, -IOR, -IOW and a few
others) are placed in a tri-stated condition (neither high or low)
and then the CPU asserts the HLDA signal which tells the DMA
@ -397,12 +397,12 @@
location.</para>
<para>The DMA will then let the device that requested the DMA
transfer know that the transfer is commencing. This is done by
transfer know that the transfer is commencing. This is done by
asserting the -DACK signal, or in the case of the floppy disk
controller, -DACK2 is asserted.</para>
<para>The floppy disk controller is now responsible for placing the
byte to be transferred on the bus Data lines. Unless the floppy
byte to be transferred on the bus Data lines. Unless the floppy
controller needs more time to get the data byte on the bus (and if
the peripheral does need more time it alerts the DMA via the READY
signal), the DMA will wait one DMA clock, and then de-assert the
@ -412,22 +412,22 @@
<para>Since the DMA cycle only transfers a single byte at a time,
the FDC now drops the DRQ2 signal, so the DMA knows that it is no
longer needed. The DMA will de-assert the -DACK2 signal, so that
longer needed. The DMA will de-assert the -DACK2 signal, so that
the FDC knows it must stop placing data on the bus.</para>
<para>The DMA will now check to see if any of the other DMA channels
have any work to do. If none of the channels have their DRQ lines
have any work to do. If none of the channels have their DRQ lines
asserted, the DMA controller has completed its work and will now
tri-state the -MEMR, -MEMW, -IOR, -IOW and address signals.</para>
<para>Finally, the DMA will de-assert the HRQ signal. The CPU sees
this, and de-asserts the HOLDA signal. Now the CPU activates its
<para>Finally, the DMA will de-assert the HRQ signal. The CPU sees
this, and de-asserts the HOLDA signal. Now the CPU activates its
-MEMR, -MEMW, -IOR, -IOW and address lines, and it resumes
executing instructions and accessing main memory and the
peripherals.</para>
<para>For a typical floppy disk sector, the above process is
repeated 512 times, once for each byte. Each time a byte is
repeated 512 times, once for each byte. Each time a byte is
transferred, the address register in the DMA is incremented and
the counter in the DMA that shows how many bytes are to be
transferred is decremented.</para>
@ -435,7 +435,7 @@
<para>When the counter reaches zero, the DMA asserts the EOP signal,
which indicates that the counter has reached zero and no more data
will be transferred until the DMA controller is reprogrammed by
the CPU. This event is also called the Terminal Count (TC).
the CPU. This event is also called the Terminal Count (TC).
There is only one EOP signal, and since only DMA channel can be
active at any instant, the DMA channel that is currently active
must be the DMA channel that just completed its task.</para>
@ -446,10 +446,10 @@
When that happens, it means the DMA will not transfer any more
information for that peripheral without intervention by the CPU.
The peripheral can then assert one of the interrupt signals to get
the processors' attention. In the PC architecture, the DMA chip
itself is not capable of generating an interrupt. The peripheral
the processors' attention. In the PC architecture, the DMA chip
itself is not capable of generating an interrupt. The peripheral
and its associated hardware is responsible for generating any
interrupt that occurs. Subsequently, it is possible to have a
interrupt that occurs. Subsequently, it is possible to have a
peripheral that uses DMA but does not use interrupts.</para>
<para>It is important to understand that although the CPU always
@ -470,53 +470,53 @@
<para>You may have noticed earlier that instead of the DMA setting
the address lines to 0x00123456 as we said earlier, the DMA only
set 0x3456. The reason for this takes a bit of explaining.</para>
set 0x3456. The reason for this takes a bit of explaining.</para>
<para>When the original IBM PC was designed, IBM elected to use both
DMA and interrupt controller chips that were designed for use with
the 8085, an 8-bit processor with an address space of 16 bits
(64K). Since the IBM PC supported more than 64K of memory,
(64K). Since the IBM PC supported more than 64K of memory,
something had to be done to allow the DMA to read or write memory
locations above the 64K mark. What IBM did to solve this problem
locations above the 64K mark. What IBM did to solve this problem
was to add an external data latch for each DMA channel that holds
the upper bits of the address to be read to or written from.
Whenever a DMA channel is active, the contents of that latch are
written to the address bus and kept there until the DMA operation
for the channel ends. IBM called these latches &ldquo;Page
for the channel ends. IBM called these latches &ldquo;Page
Registers&rdquo;.</para>
<para>So for our example above, the DMA would put the 0x3456 part of
the address on the bus, and the Page Register for DMA channel 2
would put 0x0012xxxx on the bus. Together, these two values form
would put 0x0012xxxx on the bus. Together, these two values form
the complete address in memory that is to be accessed.</para>
<para>Because the Page Register latch is independent of the DMA
chip, the area of memory to be read or written must not span a 64K
physical boundary. For example, if the DMA accesses memory
physical boundary. For example, if the DMA accesses memory
location 0xffff, after that transfer the DMA will then increment
the address register and the DMA will access the next byte at
location 0x0000, not 0x10000. The results of letting this happen
location 0x0000, not 0x10000. The results of letting this happen
are probably not intended.</para>
<note>
<para>&ldquo;Physical&rdquo; 64K boundaries should not be
confused with 8086-mode 64K &ldquo;Segments&rdquo;, which are
created by mathematically adding a segment register with an
offset register. Page Registers have no address overlap and are
offset register. Page Registers have no address overlap and are
mathematically OR-ed together.</para>
</note>
<para>To further complicate matters, the external DMA address
latches on the PC/AT hold only eight bits, so that gives us
8+16=24 bits, which means that the DMA can only point at memory
locations between 0 and 16Meg. For newer computers that allow
locations between 0 and 16Meg. For newer computers that allow
more than 16Meg of memory, the standard PC-compatible DMA cannot
access memory locations above 16Meg.</para>
<para>To get around this restriction, operating systems will reserve
a RAM buffer in an area below 16Meg that also does not span a
physical 64K boundary. Then the DMA will be programmed to
transfer data from the peripheral and into that buffer. Once the
physical 64K boundary. Then the DMA will be programmed to
transfer data from the peripheral and into that buffer. Once the
DMA has moved the data into this buffer, the operating system will
then copy the data from the buffer to the address where the data
is really supposed to be stored.</para>
@ -524,8 +524,8 @@
<para>When writing data from an address above 16Meg to a DMA-based
peripheral, the data must be first copied from where it resides
into a buffer located below 16Meg, and then the DMA can copy the
data from the buffer to the hardware. In FreeBSD, these reserved
buffers are called &ldquo;Bounce Buffers&rdquo;. In the MS-DOS world, they
data from the buffer to the hardware. In FreeBSD, these reserved
buffers are called &ldquo;Bounce Buffers&rdquo;. In the MS-DOS world, they
are sometimes called &ldquo;Smart Buffers&rdquo;.</para>
<note>
@ -539,17 +539,17 @@
<sect2>
<title>DMA Operational Modes and Settings</title>
<para>The 8237 DMA can be operated in several modes. The main ones
<para>The 8237 DMA can be operated in several modes. The main ones
are:</para>
<variablelist>
<varlistentry><term>Single</term>
<listitem>
<para>A single byte (or word) is transferred. The DMA must
<para>A single byte (or word) is transferred. The DMA must
release and re-acquire the bus for each additional byte.
This is commonly-used by devices that cannot transfer the
entire block of data immediately. The peripheral will
entire block of data immediately. The peripheral will
request the DMA each time it is ready for another
transfer.</para>
@ -563,19 +563,19 @@
<listitem>
<para>Once the DMA acquires the system bus, an entire block
of data is transferred, up to a maximum of 64K. If the
of data is transferred, up to a maximum of 64K. If the
peripheral needs additional time, it can assert the READY
signal to suspend the transfer briefly. READY should not
signal to suspend the transfer briefly. READY should not
be used excessively, and for slow peripheral transfers,
the Single Transfer Mode should be used instead.</para>
<para>The difference between Block and Demand is that once a
Block transfer is started, it runs until the transfer
count reaches zero. DRQ only needs to be asserted until
-DACK is asserted. Demand Mode will transfer one more
count reaches zero. DRQ only needs to be asserted until
-DACK is asserted. Demand Mode will transfer one more
bytes until DRQ is de-asserted, at which point the DMA
suspends the transfer and releases the bus back to the
CPU. When DRQ is asserted later, the transfer resumes
CPU. When DRQ is asserted later, the transfer resumes
where it was suspended.</para>
<para>Older hard disk controllers used Demand Mode until CPU
@ -592,36 +592,36 @@
<para>This mechanism allows a DMA channel to request the
bus, but then the attached peripheral device is
responsible for placing the addressing information on the
bus instead of the DMA. This is also used to implement a
bus instead of the DMA. This is also used to implement a
technique known as &ldquo;Bus Mastering&rdquo;.</para>
<para>When a DMA channel in Cascade Mode receives control of
the bus, the DMA does not place addresses and I/O control
signals on the bus like the DMA normally does when it is
active. Instead, the DMA only asserts the -DACK signal
active. Instead, the DMA only asserts the -DACK signal
for the active DMA channel.</para>
<para>At this point it is up to the peripheral connected to
that DMA channel to provide address and bus control
signals. The peripheral has complete control over the
signals. The peripheral has complete control over the
system bus, and can do reads and/or writes to any address
below 16Meg. When the peripheral is finished with the
below 16Meg. When the peripheral is finished with the
bus, it de-asserts the DRQ line, and the DMA controller
can then return control to the CPU or to some other DMA
channel.</para>
<para>Cascade Mode can be used to chain multiple DMA
controllers together, and this is exactly what DMA Channel
4 is used for in the PC architecture. When a peripheral
4 is used for in the PC architecture. When a peripheral
requests the bus on DMA channels 0, 1, 2 or 3, the slave
DMA controller asserts HLDREQ, but this wire is actually
connected to DRQ4 on the primary DMA controller instead of
to the CPU. The primary DMA controller, thinking it has
to the CPU. The primary DMA controller, thinking it has
work to do on Channel 4, requests the bus from the CPU
using HLDREQ signal. Once the CPU grants the bus to the
using HLDREQ signal. Once the CPU grants the bus to the
primary DMA controller, -DACK4 is asserted, and that wire
is actually connected to the HLDA signal on the slave DMA
controller. The slave DMA controller then transfers data
controller. The slave DMA controller then transfers data
for the DMA channel that requested it (0, 1, 2 or 3), or
the slave DMA may grant the bus to a peripheral that wants
to perform its own bus-mastering, such as a SCSI
@ -639,24 +639,24 @@
<para>When a peripheral is performing Bus Mastering, it is
important that the peripheral transmit data to or from
memory constantly while it holds the system bus. If the
memory constantly while it holds the system bus. If the
peripheral cannot do this, it must release the bus
frequently so that the system can perform refresh
operations on main memory.</para>
<para>The Dynamic RAM used in all PCs for main memory must
be accessed frequently to keep the bits stored in the
components &ldquo;charged&rdquo;. Dynamic RAM essentially consists of
components &ldquo;charged&rdquo;. Dynamic RAM essentially consists of
millions of capacitors with each one holding one bit of
data. These capacitors are charged with power to
represent a <literal>1</literal> or drained to represent a <literal>0</literal>. Because
data. These capacitors are charged with power to
represent a <literal>1</literal> or drained to represent a <literal>0</literal>. Because
all capacitors leak, power must be added at regular
intervals to keep the <literal>1</literal> values intact. The RAM chips
intervals to keep the <literal>1</literal> values intact. The RAM chips
actually handle the task of pumping power back into all of
the appropriate locations in RAM, but they must be told
when to do it by the rest of the computer so that the
refresh activity won't interfere with the computer wanting
to access RAM normally. If the computer is unable to
to access RAM normally. If the computer is unable to
refresh memory, the contents of memory will become
corrupted in just a few milliseconds.</para>
@ -679,8 +679,8 @@
Demand transfers, but when the DMA transfer counter
reaches zero, the counter and address are set back to
where they were when the DMA channel was originally
programmed. This means that as long as the peripheral
requests transfers, they will be granted. It is up to the
programmed. This means that as long as the peripheral
requests transfers, they will be granted. It is up to the
CPU to move new data into the fixed buffer ahead of where
the DMA is about to transfer it when doing output
operations, and read new data out of the buffer behind
@ -688,7 +688,7 @@
operations.</para>
<para>This technique is frequently used on audio devices
that have small or no hardware &ldquo;sample&rdquo; buffers. There
that have small or no hardware &ldquo;sample&rdquo; buffers. There
is additional CPU overhead to manage this &ldquo;circular&rdquo;
buffer, but in some cases this may be the only way to
eliminate the latency that occurs when the DMA counter
@ -706,7 +706,7 @@
<title>Programming the DMA</title>
<para>The DMA channel that is to be programmed should always be
&ldquo;masked&rdquo; before loading any settings. This is because the
&ldquo;masked&rdquo; before loading any settings. This is because the
hardware might unexpectedly assert the DRQ for that channel, and
the DMA might respond, even though not all of the parameters have
been loaded or updated.</para>
@ -715,8 +715,8 @@
transfer (memory-to-I/O or I/O-to-memory), what mode of DMA
operation is to be used for the transfer (Single, Block, Demand,
Cascade, etc), and finally the address and length of the transfer
are loaded. The length that is loaded is one less than the amount
you expect the DMA to transfer. The LSB and MSB of the address
are loaded. The length that is loaded is one less than the amount
you expect the DMA to transfer. The LSB and MSB of the address
and length are written to the same 8-bit I/O port, so another port
must be written to first to guarantee that the DMA accepts the
first byte as the LSB and the second byte as the MSB of the length
@ -727,14 +727,14 @@
ports.</para>
<para>Once all the settings are ready, the DMA channel can be
un-masked. That DMA channel is now considered to be &ldquo;armed&rdquo;,
un-masked. That DMA channel is now considered to be &ldquo;armed&rdquo;,
and will respond when the DRQ line for that channel is
asserted.</para>
<para>Refer to a hardware data book for precise programming details
for the 8237. You will also need to refer to the I/O port map for
for the 8237. You will also need to refer to the I/O port map for
the PC system, which describes where the DMA and Page Register
ports are located. A complete port map table is located
ports are located. A complete port map table is located
below.</para>
</sect2>
@ -743,8 +743,8 @@
<title>DMA Port Map</title>
<para>All systems based on the IBM-PC and PC/AT have the DMA
hardware located at the same I/O ports. The complete list is
provided below. Ports assigned to DMA Controller #2 are undefined
hardware located at the same I/O ports. The complete list is
provided below. Ports assigned to DMA Controller #2 are undefined
on non-AT designs.</para>
@ -1241,14 +1241,14 @@
<para>The Intel 82374 EISA System Component (ESC) was introduced
in early 1996 and includes a DMA controller that provides a
superset of 8237 functionality as well as other PC-compatible
core peripheral components in a single package. This chip is
core peripheral components in a single package. This chip is
targeted at both EISA and PCI platforms, and provides modern DMA
features like scatter-gather, ring buffers as well as direct
access by the system DMA to all 32 bits of address space.</para>
<para>If these features are used, code should also be included to
provide similar functionality in the previous 16 years worth of
PC-compatible computers. For compatibility reasons, some of the
PC-compatible computers. For compatibility reasons, some of the
82374 registers must be programmed <emphasis>after</emphasis>
programming the traditional 8237 registers for each transfer.
Writing to a traditional 8237 register forces the contents of
@ -1653,7 +1653,7 @@
<sect1 id="internals-vm">
<title>The FreeBSD VM System</title>
<para><emphasis>Contributed by &a.dillon;. 6 Feb 1999</emphasis></para>
<para><emphasis>Contributed by &a.dillon;. 6 Feb 1999</emphasis></para>
<sect2>
<title>Management of physical
@ -1666,7 +1666,7 @@
queues.</para>
<para>A page can be in a wired, active, inactive, cache, or free
state. Except for the wired state, the page is typically placed in a
state. Except for the wired state, the page is typically placed in a
doubly link list queue representing the state that it is in. Wired
pages are not placed on any queue.</para>
@ -1684,9 +1684,9 @@
in the page's flags.</para>
<para>In general terms, each of the paging queues operates in a LRU
fashion. A page is typicaly placed in a wired or active state
fashion. A page is typicaly placed in a wired or active state
initially. When wired, the page is usually associated with a page
table somewhere. The VM system ages the page by scanning pages in a
table somewhere. The VM system ages the page by scanning pages in a
more active paging queue (LRU) in order to move them to a
less-active paging queue. Pages that get moved into the cache are
still associated with a VM object but are candidates for immediate
@ -1707,12 +1707,12 @@
maintain reasonable ratios of pages in the various queues as well as
attempts to maintain a reasonable breakdown of clean vs dirty pages.
The amount of rebalancing that occurs depends on the system's memory
load. This rebalancing is implemented by the pageout daemon and
load. This rebalancing is implemented by the pageout daemon and
involves laundering dirty pages (syncing them with their backing
store), noticing when pages are activity referenced (resetting their
position in the LRU queues or moving them between queues), migrating
pages between queues when the queues are out of balance, and so
forth. FreeBSD's VM system is willing to take a reasonable number of
forth. FreeBSD's VM system is willing to take a reasonable number of
reactivation page faults to determine how active or how idle a page
actually is. This leads to better decisions being made as to when
to launder or swap-out a page.</para>
@ -1725,7 +1725,7 @@
<para>FreeBSD implements the idea of a generic &ldquo;VM
object&rdquo;. VM objects can be associated with backing store of
various types&mdash;unbacked, swap-backed, physical device-backed,
or file-backed storage. Since the filesystem uses the same VM
or file-backed storage. Since the filesystem uses the same VM
objects to manage in-core data relating to files, the result is a
unified buffer cache.</para>
@ -1762,7 +1762,7 @@
the same manner, disk I/O is typically issued by mapping portions of
objects into buffer structures and then issuing the I/O on the
buffer structures. The underlying vm_page_t's are typically busied
for the duration of the I/O. Filesystem buffers also have their own
for the duration of the I/O. Filesystem buffers also have their own
notion of being busy, which is useful to filesystem driver code
which would rather operate on filesystem buffers instead of hard VM
pages.</para>
@ -1812,7 +1812,7 @@
mappings relating to <literal>struct buf</literal> entities.</para>
<para>Unlike Linux, FreeBSD does NOT map all of physical memory into
KVM. This means that FreeBSD can handle memory configurations up to
KVM. This means that FreeBSD can handle memory configurations up to
4G on 32 bit platforms. In fact, if the mmu were capable of it,
FreeBSD could theoretically handle memory configurations up to 8TB
on a 32 bit platform. However, since most 32 bit platforms are only
@ -1837,7 +1837,7 @@
<filename>/usr/src/sys/i386/conf/<replaceable>CONFIG_FILE</replaceable></filename>. A description of all available kernel configuration options can be found in <filename>/usr/src/sys/i386/conf/LINT</filename>.</para>
<para>In a large system configuration you may wish to increase
<literal>maxusers</literal>. Values typically range from 10 to 128.
<literal>maxusers</literal>. Values typically range from 10 to 128.
Note that raising <literal>maxusers</literal> too high can cause the
system to overflow available KVM resulting in unpredictable
operation. It is better to leave maxusers at some reasonable number
@ -1849,7 +1849,7 @@
from 1024 to 4096.</para>
<para>The <literal>NBUF</literal> parameter is also traditionally used
to scale the system. This parameter determines the amount of KVA the
to scale the system. This parameter determines the amount of KVA the
system can use to map filesystem buffers for I/O. Note that this
parameter has nothing whatsoever to do with the unified buffer
cache! This parameter is dynamically tuned in 3.0-CURRENT and

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

@ -2,12 +2,12 @@
<title>Introduction</title>
<para>FreeBSD is a 4.4BSD-Lite based operating system for Intel
architecture (x86) based PCs. For an overview of FreeBSD, see
<link linkend="nutshell">FreeBSD in a nutshell</link>. For a
architecture (x86) based PCs. For an overview of FreeBSD, see
<link linkend="nutshell">FreeBSD in a nutshell</link>. For a
history of the project, read <link linkend="history">a brief
history of FreeBSD</link>. To see a description of the latest release,
history of FreeBSD</link>. To see a description of the latest release,
read <link linkend="relnotes">about the current
release</link>. If you're interested in contributing something to the
release</link>. If you're interested in contributing something to the
FreeBSD project (code, equipment, sacks of unmarked bills), please see
about <link linkend="contrib">contributing to FreeBSD</link>.</para>
@ -17,10 +17,10 @@
<para>FreeBSD is a state of the art operating system for personal
computers based on the Intel CPU architecture, which includes the
386, 486 and Pentium processors (both SX and DX versions). Intel
compatible CPUs from AMD and Cyrix are supported as well. FreeBSD
386, 486 and Pentium processors (both SX and DX versions). Intel
compatible CPUs from AMD and Cyrix are supported as well. FreeBSD
provides you with many advanced features previously available only
on much more expensive computers. These features include:</para>
on much more expensive computers. These features include:</para>
<itemizedlist>
@ -34,14 +34,14 @@
<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
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
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
@ -77,13 +77,13 @@
<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
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
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>
@ -103,7 +103,7 @@
<listitem>
<para>A full complement of <emphasis>C</emphasis>,
<emphasis>C++</emphasis> and <emphasis>Fortran</emphasis> development tools. Many
<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>
@ -111,7 +111,7 @@
<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
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>
@ -131,15 +131,15 @@
<para>FreeBSD is based on the 4.4BSD-Lite release from Computer
Systems Research Group (CSRG) at the University of California at
Berkeley, and carries on the distinguished tradition of BSD systems
development. In addition to the fine work provided by CSRG, the
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
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
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!
@ -153,7 +153,7 @@
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
vendors. Here is just a sampling of some of the applications in
which people are currently using FreeBSD:</para>
@ -205,7 +205,7 @@
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
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
@ -216,7 +216,7 @@
<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
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
@ -238,7 +238,7 @@
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
central server. FreeBSD can even boot &ldquo;diskless&rdquo;, making
individual workstations even cheaper and easier to
administer.</para>
</listitem>
@ -254,7 +254,7 @@
<para>FreeBSD is available in both source and binary form on CDROM and
via anonymous ftp. See <link linkend="mirrors">Obtaining
via anonymous ftp. See <link linkend="mirrors">Obtaining
FreeBSD</link> for more details.</para>
</sect1>
@ -271,89 +271,89 @@
<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
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
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
&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
&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
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
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
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
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
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;
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
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
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
of 4.4BSD-Lite bits. The &ldquo;Lite&rdquo; releases were light in part because
Berkeley's CSRG had removed large chunks of code required for
actually constructing a bootable running system (due to various
legal requirements) and the fact that the Intel port of 4.4 was
highly incomplete. It took the project until December of 1994 to
highly incomplete. It took the project until December of 1994 to
make this transition, and in January of 1995 it released FreeBSD 2.0
to the net and on CDROM. Despite being still more than a little
to the net and on CDROM. Despite being still more than a little
rough around the edges, the release was a significant success and
was followed by the more robust and easier to install FreeBSD 2.0.5
release in June of 1995.</para>
<para>We released FreeBSD 2.1.5 in August of 1996, and it appeared to
be popular enough among the ISP and commercial communities that
another release along the 2.1-stable branch was merited. This was
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
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
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
<para>The tree branched again on Jan 20, 1999. This led to
4.0-current and a 3.x-stable branch, from which 3.1 will be
released on February 15th, 1999.</para>
@ -368,20 +368,20 @@
<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
may be used for any purpose and without strings attached. Many of
us have a significant investment in the code (and project) and would
certainly not mind a little financial compensation now and then, but
we're definitely not prepared to insist on it. We believe that our
we're definitely not prepared to insist on it. We believe that our
first and foremost &ldquo;mission&rdquo; is to provide code to any and all
comers, and for whatever purpose, so that the code gets the widest
possible use and provides the widest possible benefit. This is, I
possible use and provides the widest possible benefit. This is, I
believe, one of the most fundamental goals of Free Software and one
that we enthusiastically support.</para>
<para>That code in our source tree which falls under the GNU Public
License (GPL) or GNU Library Public License (GLPL) comes with
slightly more strings attached, though at least on the side of
enforced access rather than the usual opposite. Due to the
enforced access rather than the usual opposite. Due to the
additional complexities that can evolve in the commercial use of GPL
software, we do, however, endeavor to replace such software with
submissions under the more relaxed BSD copyright whenever possible.</para>
@ -396,13 +396,13 @@
<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
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
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>
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
@ -415,10 +415,10 @@
<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
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
well. Please refer to the
<link linkend="synching">Synchronizing your source
tree</link> section for more information on doing this.</para>
</listitem>
@ -433,7 +433,7 @@
the CVS tree, and are thus authorized to make modifications
to the FreeBSD source (the term &ldquo;committer&rdquo; comes from the
<citerefentry><refentrytitle>cvs</refentrytitle><manvolnum>1</manvolnum></citerefentry> <command>commit</command> command, which is used to
bring new changes into the CVS repository). The best way of
bring new changes into the CVS repository). The best way of
making submissions for review by the committers list is to
use the <citerefentry><refentrytitle>send-pr</refentrytitle><manvolnum>1</manvolnum></citerefentry> 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>
@ -445,9 +445,9 @@
<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
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
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.
@ -479,7 +479,7 @@
<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
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
@ -501,7 +501,7 @@
<para>In summary, our development model is organized as a loose set of
concentric circles. The centralized model is designed for the
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
@ -521,16 +521,16 @@
<para>FreeBSD is a freely available, full source 4.4BSD-Lite based
release for Intel i386/i486/Pentium/PentiumPro/Pentium II (or
compatible) based PC's. It is based primarily on software from U.C.
compatible) based PC's. It is based primarily on software from U.C.
Berkeley's CSRG group, with some enhancements from NetBSD, OpenBSD,
386BSD, and the Free Software Foundation.</para>
<para>Since our release of FreeBSD 2.0 in January of 95, the
performance, feature set, and stability of FreeBSD has improved
dramatically. The largest change is a revamped virtual memory
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
configuration a more acceptable minimum. Other enhancements include
full NIS client and server support, transaction TCP support,
dial-on-demand PPP, an improved SCSI subsystem, early ISDN support,
support for FDDI and Fast Ethernet (100Mbit) adapters, improved
@ -539,24 +539,24 @@
<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
sane and easily understood installation process. Your feedback on
this (constantly evolving) process is especially welcome!</para>
<para>In addition to the base distributions, FreeBSD offers a new
ported software collection with hundreds of commonly sought-after
programs. At the end of August 1998 there were more than 1700 ports!
programs. At the end of August 1998 there were more than 1700 ports!
The list of ports ranges from http (WWW) servers, to games,
languages, editors and almost everything in between. The entire
languages, editors and almost everything in between. The entire
ports collection requires approximately 26MB of storage, all ports
being expressed as &ldquo;deltas&rdquo; to their original sources. This
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
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
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
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>
@ -564,7 +564,7 @@
<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
running FreeBSD 2.1 or later. You may view the locally installed
manuals with any HTML capable browser using the following
URLs:</para>
@ -593,12 +593,12 @@
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
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
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
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
@ -606,7 +606,7 @@
(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
any messy export issues to deal with. If you are outside (or even
inside) the U.S., give it a try!</para>
</sect1>

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

@ -5,7 +5,7 @@
1995.</emphasis></para>
<para>This large section of the handbook discusses the basics of
building your own custom kernel for FreeBSD. This section is
building your own custom kernel for FreeBSD. This section is
appropriate for both novice system administrators and those with
advanced Unix experience.</para>
@ -14,12 +14,12 @@
<title>Why Build a Custom Kernel?</title>
<para>Building a custom kernel is one of the most important rites of
passage every Unix system administrator must endure. This process,
passage every Unix system administrator must endure. This process,
while time-consuming, will provide many benefits to your FreeBSD
system. Unlike the <literal>GENERIC</literal> kernel, which must support every
system. Unlike the <literal>GENERIC</literal> kernel, which must support every
possible SCSI and network card, along with tons of other rarely used
hardware support, a custom kernel only contains support for
<emphasis>your</emphasis> PC's hardware. This has a number of
<emphasis>your</emphasis> PC's hardware. This has a number of
benefits:</para>
@ -35,7 +35,7 @@
because the kernel is the one process which must always be
present in memory, and so all of that unused code ties up
pages of RAM that your programs would otherwise be able to
use. Therefore, on a system with limited RAM, building a
use. Therefore, on a system with limited RAM, building a
custom kernel is of critical importance.</para>
</listitem>
@ -57,14 +57,14 @@
<para>First, let us take a quick tour of the kernel build directory.
All directories mentioned will be relative to the main
<filename>/usr/src/sys</filename> directory, which is also
accessible through <filename>/sys</filename>. There are a number of
accessible through <filename>/sys</filename>. There are a number of
subdirectories here representing different parts of the kernel, but
the most important, for our purposes, are
<filename>i386/conf</filename>, where you will edit your custom
kernel configuration, and <filename>compile</filename>,
which is the staging area where your kernel will be built. Notice
which is the staging area where your kernel will be built. Notice
the logical organization of the directory tree, with each supported
device, filesystem, and option in its own subdirectory. Also,
device, filesystem, and option in its own subdirectory. Also,
anything inside the <filename>i386</filename> directory deals with
PC hardware only, while everything outside the
<filename>i386</filename> directory is common to all platforms which
@ -73,7 +73,7 @@
<note>
<para>If there is <emphasis>not</emphasis> a
<filename>/usr/src/sys</filename> directory on your system, then
the kernel source has not been been installed. The easiest way
the kernel source has not been been installed. The easiest way
to do this is by running <command>/stand/sysinstall</command> as
<username>root</username>, choosing <literal>Configure</literal>,
then <literal>Distributions</literal>, then <literal>src</literal>,
@ -82,7 +82,7 @@
<para>Next, move to the <filename>i386/conf</filename> directory and
copy the <filename>GENERIC</filename> configuration file to the name
you want to give your kernel. For example:</para>
you want to give your kernel. For example:</para>
<screen>&prompt.root; <userinput>cd /usr/src/sys/i386/conf</userinput>
@ -92,7 +92,7 @@
<para>Traditionally, this name is in all capital
letters and, if you are maintaining multiple FreeBSD machines with
different hardware, it is a good idea to name it after your
machine's hostname. We will call it <filename>MYKERNEL</filename>
machine's hostname. We will call it <filename>MYKERNEL</filename>
for the purpose of this example.</para>
<note>
@ -102,17 +102,17 @@
</note>
<para>Now, edit <filename>MYKERNEL</filename> with your favorite text
editor. If you are just starting out, the only editor available
editor. If you are just starting out, the only editor available
will probably be <command>vi</command>, which is too
complex to explain here, but is covered well in many books in the
<link
linkend="bibliography">bibliography</link>. Feel free to change
linkend="bibliography">bibliography</link>. Feel free to change
the comment lines at the top to reflect your configuration or the
changes you have made to differentiate it from
<filename>GENERIC</filename>.</para>
<para>If you have build a kernel under SunOS or some other BSD
operating system, much of this file will be very familiar to you. If
operating system, much of this file will be very familiar to you. If
you are coming from some other operating system such as DOS, on the
other hand, the <filename>GENERIC</filename> configuration file
might seem overwhelming to you, so follow the descriptions in the
@ -123,9 +123,9 @@
<para>If you are trying to upgrade your kernel from an older version
of FreeBSD, you will probably have to get a new version of
<citerefentry><refentrytitle>config</refentrytitle><manvolnum>8</manvolnum></citerefentry> from the same place you got the new
kernel sources. It is located in
kernel sources. It is located in
<filename>/usr/src/usr.sbin</filename>, so you will need to
download those sources as well. Re-build and install it before
download those sources as well. Re-build and install it before
running the next commands.</para>
</note>
@ -142,8 +142,8 @@
<para>The new kernel will be copied to the root
directory as <filename>/kernel</filename> and the old kernel will be
moved to <filename>/kernel.old</filename>. Now, shutdown the system
and reboot to use your kernel. In case something goes wrong, there
moved to <filename>/kernel.old</filename>. Now, shutdown the system
and reboot to use your kernel. In case something goes wrong, there
are some <link linkend="kernelconfig-trouble">troubleshooting</link> instructions at the end of this document.
Be sure to read the section which explains how to recover in case
your new kernel <link
@ -162,9 +162,9 @@
<sect1 id="kernelconfig-config">
<title>The Configuration File</title>
<para>The general format of a configuration file is quite simple. Each
line contains a keyword and one or more arguments. For simplicity,
most lines only contain one argument. Anything following a
<para>The general format of a configuration file is quite simple. Each
line contains a keyword and one or more arguments. For simplicity,
most lines only contain one argument. Anything following a
<literal>#</literal> is considered a comment and ignored.
The following sections describe each keyword, generally in the order
they are listed in <filename>GENERIC</filename>, although some
@ -174,21 +174,21 @@
<anchor id="kernelconfig-options"> An exhaustive list of options and
more detailed explanations of the device lines is present in the
<filename>LINT</filename> configuration file, located in the same
directory as <filename>GENERIC</filename>. If you are in doubt as to
directory as <filename>GENERIC</filename>. If you are in doubt as to
the purpose or necessity of a line, check first in
<filename>LINT</filename>.</para>
<para>The kernel is currently being moved to a better organization of
the option handling. Traditionally, each option in the config file
the option handling. Traditionally, each option in the config file
was simply converted into a <option>-D</option> switch for the
<acronym>CFLAGS</acronym> line of the kernel Makefile. Naturally,
<acronym>CFLAGS</acronym> line of the kernel Makefile. Naturally,
this caused a creeping optionism, with nobody really knowing which
option has been referenced in what files.</para>
<para>In the new scheme, every <literal>#ifdef</literal>
that is intended to be dependent upon an option gets this option out
of an <filename>opt_<replaceable>foo</replaceable>.h</filename>
declaration file created in the compile directory by <command>config</command>. The list of valid options for
declaration file created in the compile directory by <command>config</command>. The list of valid options for
<command>config</command> lives in two files: options
that do not depend on the architecture are listed in
<filename>/sys/conf/options</filename>, architecture-dependent ones
@ -248,7 +248,7 @@
different values of <replaceable>cpu_type</replaceable>
as are present in the <filename>GENERIC</filename> kernel.
For a custom kernel, it is best to specify only the cpu
you have. If, for example, you have an Intel Pentium, use
you have. If, for example, you have an Intel Pentium, use
<literal>I586_CPU</literal> for <replaceable>cpu_type</replaceable>.</para>
</listitem>
</varlistentry>
@ -257,15 +257,15 @@
<listitem>
<para>Next, we have <literal>ident</literal>,
which is the identification of the kernel. You should
which is the identification of the kernel. You should
change this from <literal>GENERIC</literal> to whatever
you named your kernel, in this example,
<literal>MYKERNEL</literal>. The value you put in
<literal>MYKERNEL</literal>. The value you put in
<literal>ident</literal> will print when you
boot up the kernel, so it is useful to give a kernel a
different name if you want to keep it separate from your
usual kernel (if you want to build an experimental kernel,
for example). Note that, as with <literal>machine</literal> and <literal>
for example). Note that, as with <literal>machine</literal> and <literal>
cpu</literal>, enclose your kernel's name in quotation
marks if it contains any numbers.</para>
@ -280,13 +280,13 @@
<listitem>
<para>This file sets the size of a number of important
system tables. This number is supposed to be roughly
system tables. This number is supposed to be roughly
equal to the number of simultaneous users you expect to
have on your machine. However, under normal
have on your machine. However, under normal
circumstances, you will want to set
<literal>maxusers</literal> to at least <literal>4</literal>,
especially if you are using the X Window System or
compiling software. The reason is that the most important
compiling software. The reason is that the most important
table set by <literal>maxusers</literal> is the
maximum number of processes, which is set to <literal>20 + 16 *
maxusers</literal>, so if you set
@ -294,11 +294,11 @@
can only have 36 simultaneous processes, including the 18
or so that the system starts up at boot time, and the 15
or so you will probably create when you start the X Window
System. Even a simple task like reading a man page will start up nine
processes to filter, decompress, and view it. Setting
System. Even a simple task like reading a man page will start up nine
processes to filter, decompress, and view it. Setting
<literal>maxusers</literal> to <literal>4</literal> will allow you
to have up to 84 simultaneous processes, which should be
enough for anyone. If, however, you see the dreaded
enough for anyone. If, however, you see the dreaded
<errorname>proc table full</errorname> error when trying to start another
program, or are running a server with a large number of
simultaneous users (like Walnut Creek CDROM's FTP site),
@ -307,10 +307,10 @@
<note>
<para><literal>maxuser</literal> does
<emphasis>not</emphasis> limit the number of users which
can log into your machine. It simply sets various table
can log into your machine. It simply sets various table
sizes to reasonable values considering the maximum
number of users you will likely have on your system and
how many processes each of them will be running. One
how many processes each of them will be running. One
keyword which <emphasis>does</emphasis> limit the number
of simultaneous <emphasis>remote logins</emphasis> is
<link
@ -325,14 +325,14 @@
<listitem>
<para>This line specifies the location and name of the
kernel. Traditionally the kernel is called
kernel. Traditionally the kernel is called
<filename>vmunix</filename> but in FreeBSD, it is aptly
named <filename>kernel</filename>. You should always use
named <filename>kernel</filename>. You should always use
<literal>kernel</literal> for
<replaceable>kernel_name</replaceable> because changing it will
render numerous system utilities inoperative. The second
render numerous system utilities inoperative. The second
part of the line specifies the disk and partition where
the root filesystem and kernel can be found. Typically
the root filesystem and kernel can be found. Typically
this will be <literal>wd0</literal> for systems
with non-SCSI drives, or <literal>sd0</literal>
for systems with SCSI drives.</para>
@ -355,14 +355,14 @@
<listitem>
<para>This line allows the kernel to simulate a math
co-processor if your computer does not have one (386 or
486SX). If you have a Pentium, a 486DX, or a 386 or 486SX
486SX). If you have a Pentium, a 486DX, or a 386 or 486SX
with a separate 387 or 487 chip, you can comment this line
out.</para>
<note>
<para>The normal math co-processor emulation routines that
come with FreeBSD are <emphasis>not</emphasis> very
accurate. If you do not have a math co-processor, and
accurate. If you do not have a math co-processor, and
you need the best accuracy, I recommend that you change
this option to <literal>GPL_MATH_EMULATE</literal> to use
the superior GNU math support, which is not included by
@ -374,7 +374,7 @@
<varlistentry><term><literal>options "COMPAT_43"</literal></term>
<listitem>
<para>Compatibility with 4.3BSD. Leave this in; some
<para>Compatibility with 4.3BSD. Leave this in; some
programs will act strangely if you comment this
out.</para>
</listitem>
@ -385,7 +385,7 @@
<listitem>
<para>ISA devices and EISA devices operating in an ISA
compatibility mode can only perform DMA (Direct Memory
Access) to memory below 16 megabytes. This option enables
Access) to memory below 16 megabytes. This option enables
such devices to work in systems with more than 16
megabytes of memory.</para>
</listitem>
@ -405,11 +405,11 @@
<varlistentry><term><literal>options SYSVSHM</literal></term>
<listitem>
<para>This option provides for System V shared memory. The
<para>This option provides for System V shared memory. The
most common use of this is the XSHM extension in X
Windows, which many graphics-intensive programs (such as
the movie player XAnim, and Linux DOOM) will automatically
take advantage of for extra speed. If you use the X
take advantage of for extra speed. If you use the X
Window System, you will definitely want to include
this.</para>
</listitem>
@ -418,7 +418,7 @@
<varlistentry><term><literal>options SYSVSEM</literal></term>
<listitem>
<para>Support for System V semaphores. Less commonly used
<para>Support for System V semaphores. Less commonly used
but only adds a few hundred bytes to the kernel.</para>
</listitem>
</varlistentry>
@ -426,7 +426,7 @@
<varlistentry><term><literal>options SYSVMSG</literal></term>
<listitem>
<para>Support for System V messages. Again, only adds a few
<para>Support for System V messages. Again, only adds a few
hundred bytes to the kernel.</para>
<note>
@ -444,7 +444,7 @@
<sect2>
<title>Filesystem Options</title>
<para>These options add support for various filesystems. You must
<para>These options add support for various filesystems. You must
include at least one of these to support the device you boot from;
typically this will be <acronym>FFS</acronym> if you boot from a
hard drive, or <acronym>NFS</acronym> if you are booting a
@ -467,7 +467,7 @@
<varlistentry><term><literal>options NFS</literal></term>
<listitem>
<para>Network Filesystem. Unless you plan to mount
<para>Network Filesystem. Unless you plan to mount
partitions from a Unix file server over Ethernet, you can
comment this out.</para>
</listitem>
@ -476,11 +476,11 @@
<varlistentry><term><literal>options MSDOSFS</literal></term>
<listitem>
<para>MS-DOS Filesystem. Unless you plan to mount a DOS
<para>MS-DOS Filesystem. Unless you plan to mount a DOS
formatted hard drive partition at boot time, you can
safely comment this out. It will be automatically loaded
safely comment this out. It will be automatically loaded
the first time you mount a DOS partition, as described
above. Also, the excellent <application>mtools</application> software (in the ports
above. Also, the excellent <application>mtools</application> software (in the ports
collection) allows you to access DOS floppies without
having to mount and unmount them (and does not require
MSDOSFS at all).</para>
@ -490,10 +490,10 @@
<varlistentry><term><literal>options "CD9660"</literal></term>
<listitem>
<para>ISO 9660 filesystem for CD-ROMs. Comment it out if
<para>ISO 9660 filesystem for CD-ROMs. Comment it out if
you do not have a CD-ROM drive or only mount data CD's
occasionally (since it will be dynamically loaded the
first time you mount a data CD). Audio CD's do not need
first time you mount a data CD). Audio CD's do not need
this filesystem.</para>
</listitem>
</varlistentry>
@ -501,7 +501,7 @@
<varlistentry><term><literal>options PROCFS</literal></term>
<listitem>
<para>Process filesystem. This is a pretend filesystem
<para>Process filesystem. This is a pretend filesystem
mounted on <filename>/proc</filename> which allows
programs like <citerefentry><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry> to give you more
information on what processes are running.</para>
@ -511,12 +511,12 @@
<varlistentry><term><literal>options MFS</literal></term>
<listitem>
<para>Memory-mapped file system. This is basically a RAM
<para>Memory-mapped file system. This is basically a RAM
disk for fast storage of temporary files, useful if you
have a lot of swap space that you want to take advantage
of. A perfect place to mount an MFS partition is on the
of. A perfect place to mount an MFS partition is on the
<filename>/tmp</filename> directory, since many programs
store temporary data here. To mount an MFS RAM disk on
store temporary data here. To mount an MFS RAM disk on
<filename>/tmp</filename>, add the following line to
<filename>/etc/fstab</filename> and then reboot or type
<command>mount /tmp</command>:</para>
@ -547,8 +547,8 @@
<varlistentry><term><literal>options "EXT2FS"</literal></term>
<listitem>
<para>Linux's native file system. With ext2fs support you
are able to read and write to Linux partitions. This is
<para>Linux's native file system. With ext2fs support you
are able to read and write to Linux partitions. This is
useful if you dual-boot FreeBSD and Linux and want to
share data between the two systems.</para>
</listitem>
@ -557,10 +557,10 @@
<varlistentry><term><literal>options QUOTA</literal></term>
<listitem>
<para>Enable disk quotas. If you have a public access
<para>Enable disk quotas. If you have a public access
system, and do not want users to be able to overflow the
<filename>/home</filename> partition, you can establish
disk quotas for each user. Refer to the
disk quotas for each user. Refer to the
<link linkend="quotas">Disk Quotas</link> section for
more information.</para>
</listitem>
@ -574,7 +574,7 @@
<title>Basic Controllers and Devices</title>
<para>These sections describe the basic disk, tape, and CD-ROM
controllers supported by FreeBSD. There are separate sections for
controllers supported by FreeBSD. There are separate sections for
<link linkend="kernelconfig-scsi">SCSI</link> controllers and <link
linkend="kernelconfig-network">network</link> cards.</para>
@ -582,7 +582,7 @@
<variablelist>
<varlistentry><term><literal>controller isa0</literal></term>
<listitem>
<para>All PC's supported by FreeBSD have one of these. If
<para>All PC's supported by FreeBSD have one of these. If
you have an IBM PS/2 (Micro Channel Architecture), then
you cannot run FreeBSD at this time.</para>
</listitem>
@ -591,7 +591,7 @@
<varlistentry><term><literal>controller pci0</literal></term>
<listitem>
<para>Include this if you have a PCI motherboard. This
<para>Include this if you have a PCI motherboard. This
enables auto-detection of PCI cards and gatewaying from
the PCI to the ISA bus.</para>
</listitem>
@ -604,7 +604,7 @@
<devicename>A:</devicename> floppy drive, and
<literal>fd1</literal> is the <devicename>B:</devicename> drive.
<literal>ft0</literal> is a QIC-80 tape drive
attached to the floppy controller. Comment out any lines
attached to the floppy controller. Comment out any lines
corresponding to devices you do not have.</para>
<note>
@ -618,10 +618,10 @@
<varlistentry><term><literal>controller wdc0</literal></term>
<listitem>
<para>This is the primary IDE controller. <literal>wd0</literal> and <literal>wd1</literal> are the master and slave hard
drive, respectively. <literal>wdc1</literal> is
<para>This is the primary IDE controller. <literal>wd0</literal> and <literal>wd1</literal> are the master and slave hard
drive, respectively. <literal>wdc1</literal> is
a secondary IDE controller where you might have a third or
fourth hard drive, or an IDE CD-ROM. Comment out the
fourth hard drive, or an IDE CD-ROM. Comment out the
lines which do not apply (if you have a SCSI hard drive,
you will probably want to comment out all six lines, for
example).</para>
@ -631,11 +631,11 @@
<varlistentry><term><literal>device wcd0<anchor id="kernelconfig-atapi"></literal></term>
<listitem>
<para>This device provides IDE CD-ROM support. Be sure to
<para>This device provides IDE CD-ROM support. Be sure to
leave <literal>wdc0</literal> uncommented, and
<literal>wdc1</literal> if you have more than
one IDE controller and your CD-ROM is on the second one
card. To use this, you must also include the line
card. To use this, you must also include the line
<literal>options ATAPI</literal>.</para>
</listitem>
</varlistentry>
@ -646,7 +646,7 @@
<listitem>
<para><literal>npx0</literal> is the interface to
the floating point math unit in FreeBSD, either the
hardware co-processor or the software math emulator. It
hardware co-processor or the software math emulator. It
is <emphasis>not</emphasis> optional.</para>
</listitem>
</varlistentry>
@ -664,10 +664,10 @@
<listitem>
<para>The following drivers are for the so-called
<emphasis>proprietary</emphasis> CD-ROM drives. These
<emphasis>proprietary</emphasis> CD-ROM drives. These
drives have their own controller card or might plug into a
sound card such as the SoundBlaster 16. They are
<emphasis>not</emphasis> IDE or SCSI. Most older
sound card such as the SoundBlaster 16. They are
<emphasis>not</emphasis> IDE or SCSI. Most older
single-speed and double-speed CD-ROMs use these
interfaces, while newer quad-speeds are likely to be <link
linkend="kernelconfig-atapi">IDE</link> or <link
@ -718,7 +718,7 @@
<varlistentry><term>SCSI Controllers</term>
<listitem>
<para>The next ten or so lines include support for different
kinds of SCSI controllers. Comment out all except for the
kinds of SCSI controllers. Comment out all except for the
one(s) you have:</para>
@ -812,10 +812,10 @@
<listitem>
<para>This causes the kernel to pause 15 seconds before
probing each SCSI device in your system. If you only have
probing each SCSI device in your system. If you only have
IDE hard drives, you can ignore this, otherwise you will
probably want to lower this number, perhaps to 5 seconds,
to speed up booting. Of course if you do this, and
to speed up booting. Of course if you do this, and
FreeBSD has trouble recognizing your SCSI devices, you
will have to raise it back up.</para>
</listitem>
@ -825,7 +825,7 @@
<listitem>
<para>If you have any SCSI controllers, this line provides
generic SCSI support. If you do not have SCSI, you can
generic SCSI support. If you do not have SCSI, you can
comment this, and the following three lines, out.</para>
</listitem>
</varlistentry>
@ -879,11 +879,11 @@
vector scintr</literal></term>
<listitem>
<para><literal>sc0</literal> is the default
console driver, which resembles an SCO console. Since most
console driver, which resembles an SCO console. Since most
full-screen programs access the console through a terminal
database library like <filename>termcap</filename>, it
should not matter much whether you use this or <literal>vt0</literal>, the VT220 compatible console
driver. When you log in, set your <envar>TERM</envar> variable to
driver. When you log in, set your <envar>TERM</envar> variable to
&ldquo;scoansi&rdquo; if full-screen programs have trouble running
under this console.</para>
</listitem>
@ -894,9 +894,9 @@
<listitem>
<para>This is a VT220-compatible console driver, backwards
compatible to VT100/102. It works well on some laptops
which have hardware incompatibilities with <literal>sc0</literal>. Also, set your <envar>TERM</envar> variable
to <literal>vt100</literal> or <literal>vt220</literal> when you log in. This driver
compatible to VT100/102. It works well on some laptops
which have hardware incompatibilities with <literal>sc0</literal>. Also, set your <envar>TERM</envar> variable
to <literal>vt100</literal> or <literal>vt220</literal> when you log in. This driver
might also prove useful when connecting to a large number
of different machines over the network, where the
<filename>termcap</filename> or
@ -915,7 +915,7 @@
<varlistentry><term><literal>options XSERVER</literal></term>
<listitem>
<para>Only applicable with the <literal>vt0</literal> console driver. This
<para>Only applicable with the <literal>vt0</literal> console driver. This
includes code required to run the <application>XFree86</application> X Window Server
under the <literal>vt0</literal>
console driver.</para>
@ -958,8 +958,8 @@
<sect2>
<title>Serial and Parallel Ports</title>
<para>Nearly all systems have these. If you are attaching a printer
to one of these ports, the <link linkend="printing">Printing</link> section of the handbook is very useful. If
<para>Nearly all systems have these. If you are attaching a printer
to one of these ports, the <link linkend="printing">Printing</link> section of the handbook is very useful. If
you are using modem, <link linkend="dialup">Dialup access</link> provides extensive detail on serial port
configuration for use with such devices.</para>
@ -973,10 +973,10 @@
Note that if you have an internal modem on COM4 and a
serial port at COM2 you will have to change the IRQ of the
modem to 2 (for obscure technical reasons IRQ 2 = IRQ 9)
in order to access it from FreeBSD. If you have a
in order to access it from FreeBSD. If you have a
multiport serial card, check the manual page for
<citerefentry><refentrytitle>sio</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information on the
proper values for these lines. Some video cards (notably
proper values for these lines. Some video cards (notably
those based on S3 chips) use IO addresses of the form
<literal>0x*2e8</literal>, and since many cheap serial
cards do not fully decode the 16-bit IO address space,
@ -995,7 +995,7 @@
<listitem>
<para><literal>lpt0</literal> through <literal>lpt2</literal> are the three printer ports you
could conceivably have. Most people just have one,
could conceivably have. Most people just have one,
though, so feel free to comment out the other two lines if
you do not have them.</para>
</listitem>
@ -1009,7 +1009,7 @@
<title>Networking</title>
<para>FreeBSD, as with Unix in general, places a
<emphasis>big</emphasis> emphasis on networking. Therefore, even
<emphasis>big</emphasis> emphasis on networking. Therefore, even
if you do not have an Ethernet card, pay attention to the
mandatory options and the dial-up networking support.</para>
@ -1017,9 +1017,9 @@
<variablelist>
<varlistentry><term><literal>options INET</literal></term>
<listitem>
<para>Networking support. Leave it in even if you do not
plan to be connected to a network. Most programs require
at least loopback networking (i.e. making network
<para>Networking support. Leave it in even if you do not
plan to be connected to a network. Most programs require
at least loopback networking (i.e. making network
connections within your PC) so this is essentially
mandatory.</para>
</listitem>
@ -1029,8 +1029,8 @@
<listitem>
<para>The next lines enable support for various Ethernet
cards. If you do not have a network card, you can comment
out all of these lines. Otherwise, you will want to leave
cards. If you do not have a network card, you can comment
out all of these lines. Otherwise, you will want to leave
in support for your particular Ethernet card(s):</para>
@ -1181,9 +1181,9 @@
<listitem>
<para><literal>loop</literal> is the generic
loopback device for TCP/IP. If you telnet or FTP to
<hostid>localhost</hostid> (a.k.a. <hostid role="ipaddr">127.0.0.1</hostid>) it will come back at you
through this pseudo-device. Mandatory.</para>
loopback device for TCP/IP. If you telnet or FTP to
<hostid>localhost</hostid> (a.k.a. <hostid role="ipaddr">127.0.0.1</hostid>) it will come back at you
through this pseudo-device. Mandatory.</para>
</listitem>
</varlistentry>
@ -1201,12 +1201,12 @@
<listitem>
<para><literal>sl</literal> is for SLIP (Serial
Line Internet Protocol) support. This has been almost
Line Internet Protocol) support. This has been almost
entirely supplanted by PPP, which is easier to set up,
better suited for modem-to-modem connections, as well as
more powerful. The <replaceable>number</replaceable> after
more powerful. The <replaceable>number</replaceable> after
<literal>sl</literal> specifies how many
simultaneous SLIP sessions to support. This handbook has
simultaneous SLIP sessions to support. This handbook has
more information on setting up a SLIP <link
linkend="slipc">client</link> or <link linkend="slips">server</link>.</para>
</listitem>
@ -1218,11 +1218,11 @@
<listitem>
<para><literal>ppp</literal> is for kernel-mode
PPP (Point-to-Point Protocol) support for dial-up Internet
connections. There is also version of PPP implemented as a
connections. There is also version of PPP implemented as a
user application that uses the <devicename>tun</devicename> and offers more flexibility and
features such as demand dialing. If you still want to use
features such as demand dialing. If you still want to use
this PPP driver, read the <link linkend="ppp">kernel-mode PPP</link>
section of the handbook. As with the <literal>sl</literal> device,
section of the handbook. As with the <literal>sl</literal> device,
<replaceable>number</replaceable> specifies how many
simultaneous PPP connections to support.</para>
</listitem>
@ -1233,10 +1233,10 @@
<listitem>
<para><literal>tun</literal> is used by the
user-mode PPP software. This program is easy to set up and
very fast. It also has special features such as automatic
dial-on-demand. The number after <literal>tun</literal> specifies the number of
simultaneous PPP sessions to support. See the <link
user-mode PPP software. This program is easy to set up and
very fast. It also has special features such as automatic
dial-on-demand. The number after <literal>tun</literal> specifies the number of
simultaneous PPP sessions to support. See the <link
linkend="userppp">user-mode PPP</link> section of the handbook for more
information.</para>
</listitem>
@ -1246,17 +1246,17 @@
<replaceable>number</replaceable></literal></term>
<listitem>
<para>Berkeley packet filter. This pseudo-device allows
<para>Berkeley packet filter. This pseudo-device allows
network interfaces to be placed in promiscuous mode,
capturing every packet on a broadcast network (e.g. an
ethernet). These packets can be captured to disk and/or
capturing every packet on a broadcast network (e.g. an
ethernet). These packets can be captured to disk and/or
examined with the <citerefentry><refentrytitle>tcpdump</refentrytitle><manvolnum>1</manvolnum></citerefentry> program.
Note that implementation of this capability can seriously
compromise your overall network security. The
compromise your overall network security. The
<replaceable>number</replaceable> after bpfilter is the number
of interfaces that can be examined simultaneously.
Optional, not recommended except for those who are fully
aware of the potential pitfalls. Not all network cards
aware of the potential pitfalls. Not all network cards
support this capability.</para>
</listitem>
</varlistentry>
@ -1269,7 +1269,7 @@
<title>Sound cards</title>
<para>This is the first section containing lines that are not in the
GENERIC kernel. To include sound card support, you will have to
GENERIC kernel. To include sound card support, you will have to
copy the appropriate lines from the LINT kernel (which contains
support for <emphasis>every</emphasis> device) as follows:</para>
@ -1277,7 +1277,7 @@
<variablelist>
<varlistentry><term><literal>controller snd0</literal></term>
<listitem>
<para>Generic sound driver code. Required for all of the
<para>Generic sound driver code. Required for all of the
following sound cards except <literal>pca</literal>.</para>
</listitem>
</varlistentry>
@ -1324,7 +1324,7 @@
<varlistentry><term><literal>device sbmidi0 at isa? port 0x330</literal></term>
<listitem>
<para>SoundBlaster 16 MIDI interface. If you have a
<para>SoundBlaster 16 MIDI interface. If you have a
SoundBlaster 16, you must include this line, or the kernel
will not compile.</para>
</listitem>
@ -1350,7 +1350,7 @@
conflicts</literal></term>
<listitem>
<para>AdLib FM-synthesis audio. Include this line for
<para>AdLib FM-synthesis audio. Include this line for
AdLib, SoundBlaster, and ProAudioSpectrum users, if you
want to play MIDI songs with a program such as <command>playmidi</command> (in the ports
collection).</para>
@ -1377,7 +1377,7 @@
tty</literal><anchor id="kernelconfig-pcaudio"></term>
<listitem>
<para>Digital audio through PC speaker. This is going to be
<para>Digital audio through PC speaker. This is going to be
very poor sound quality and quite CPU-intensive, so you
have been warned (but it does not require a sound
card).</para>
@ -1400,7 +1400,7 @@
<para>Pseudo-device drivers are parts of the kernel that act like
device drivers but do not correspond to any actual hardware in the
machine. The <link linkend="kernelconfig-network">network-related</link> pseudo-devices are in that section,
machine. The <link linkend="kernelconfig-network">network-related</link> pseudo-devices are in that section,
while the remainder are here.</para>
@ -1408,7 +1408,7 @@
<varlistentry><term><literal>pseudo-device gzip</literal></term>
<listitem>
<para><literal>gzip</literal> allows you to run
FreeBSD programs that have been compressed with <command>gzip</command>. The programs in
FreeBSD programs that have been compressed with <command>gzip</command>. The programs in
<filename>/stand</filename> are compressed so it is a good
idea to have this option in your kernel.</para>
</listitem>
@ -1418,7 +1418,7 @@
<listitem>
<para><literal>log</literal> is used for logging
of kernel error messages. Mandatory.</para>
of kernel error messages. Mandatory.</para>
</listitem>
</varlistentry>
@ -1427,12 +1427,12 @@
<listitem>
<para><literal>pty</literal> is a
&ldquo;pseudo-terminal&rdquo; or simulated login port. It is used
&ldquo;pseudo-terminal&rdquo; or simulated login port. It is used
by incoming <command>telnet</command> and
<command>rlogin</command> sessions, xterm, and
some other applications such as emacs. The
some other applications such as emacs. The
<replaceable>number</replaceable> indicates the number of
<literal>pty</literal>s to create. If you need
<literal>pty</literal>s to create. If you need
more than <filename>GENERIC</filename> default of 16 simultaneous xterm windows
and/or remote logins, be sure to increase this number
accordingly, up to a maximum of 256.</para>
@ -1443,24 +1443,24 @@
<replaceable>number</replaceable></literal></term>
<listitem>
<para>Snoop device. This pseudo-device allows one terminal
<para>Snoop device. This pseudo-device allows one terminal
session to watch another using the
<citerefentry><refentrytitle>watch</refentrytitle><manvolnum>8</manvolnum></citerefentry> command. Note that
<citerefentry><refentrytitle>watch</refentrytitle><manvolnum>8</manvolnum></citerefentry> command. Note that
implementation of this capability has important security
and privacy implications. The <replaceable>number</replaceable>
and privacy implications. The <replaceable>number</replaceable>
after snp is the total number of simultaneous snoop
sessions. Optional.</para>
sessions. Optional.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>pseudo-device vn</literal></term>
<listitem>
<para>Vnode driver. Allows a file to be treated as a device
<para>Vnode driver. Allows a file to be treated as a device
after being set up with the <citerefentry><refentrytitle>vnconfig</refentrytitle><manvolnum>8</manvolnum></citerefentry>
command. This driver can be useful for manipulating
command. This driver can be useful for manipulating
floppy disk images and using a file as a swap device (e.g.
an MS Windows swap file). Optional.</para>
an MS Windows swap file). Optional.</para>
</listitem>
</varlistentry>
@ -1468,12 +1468,12 @@
<replaceable>number</replaceable></literal></term>
<listitem>
<para>Concatenated disks. This pseudo-device allows you to
<para>Concatenated disks. This pseudo-device allows you to
concatenate multiple disk partitions into one large
&ldquo;meta&rdquo;-disk. The <replaceable>number</replaceable> after ccd
&ldquo;meta&rdquo;-disk. The <replaceable>number</replaceable> after ccd
is the total number of concatenated disks (not total
number of disks that can be concatenated) that can be
created. (See <citerefentry><refentrytitle>ccd</refentrytitle><manvolnum>4</manvolnum></citerefentry> and
created. (See <citerefentry><refentrytitle>ccd</refentrytitle><manvolnum>4</manvolnum></citerefentry> and
<citerefentry><refentrytitle>ccdconfig</refentrytitle><manvolnum>8</manvolnum></citerefentry> man pages for more
details.) Optional.</para>
</listitem>
@ -1487,7 +1487,7 @@
<title>Joystick, PC Speaker, Miscellaneous</title>
<para>This section describes some miscellaneous hardware devices
supported by FreeBSD. Note that none of these lines are included
supported by FreeBSD. Note that none of these lines are included
in the GENERIC kernel, you will have to copy them from this
handbook or the LINT kernel (which contains support for
<emphasis>every</emphasis> device):</para>
@ -1504,13 +1504,13 @@
<listitem>
<para>Supports IBM BASIC-style noises through the PC
speaker. Some fun programs which use this are
speaker. Some fun programs which use this are
<filename>/usr/sbin/spkrtest</filename>, which is a shell
script that plays some simple songs, and
<filename>/usr/games/piano</filename> which lets you play
songs using the keyboard as a simple piano (this file only
exists if you have installed the
<literal>games</literal> package). Also, the excellent
<literal>games</literal> package). Also, the excellent
text role-playing game <application>NetHack</application> (in the ports collection)
can be configured to use this device to play songs when
you play musical instruments in the game.</para>
@ -1528,17 +1528,17 @@
<title>Making Device Nodes</title>
<para>Almost every device in the kernel has a corresponding &ldquo;node&rdquo;
entry in the <filename>/dev</filename> directory. These nodes look
entry in the <filename>/dev</filename> directory. These nodes look
like regular files, but are actually special entries into the kernel
which programs use to access the device. The shell script
which programs use to access the device. The shell script
<filename>/dev/MAKEDEV</filename>, which is executed when you first
install the operating system, creates nearly all of the device nodes
supported. However, it does not create <emphasis>all</emphasis> of
supported. However, it does not create <emphasis>all</emphasis> of
them, so when you add support for a new device, it pays to make sure
that the appropriate entries are in this directory, and if not, add
them. Here is a simple example:</para>
them. Here is a simple example:</para>
<para>Suppose you add the IDE CD-ROM support to the kernel. The line
<para>Suppose you add the IDE CD-ROM support to the kernel. The line
to add is:</para>
<programlisting>
@ -1548,7 +1548,7 @@ controller wcd0</programlisting>
that start with <filename>wcd0</filename> in the
<filename>/dev</filename> directory, possibly followed by a letter,
such as <literal>c</literal>, or preceded by the letter <literal>r</literal>, which means a &ldquo;raw&rdquo;
device. It turns out that those files are not there, so I must
device. It turns out that those files are not there, so I must
change to the <filename>/dev</filename> directory and type:</para>
@ -1569,7 +1569,7 @@ controller wcd0</programlisting>
<para>When creating device nodes for devices such as sound cards, if
other people have access to your machine, it may be desirable to
protect the devices from outside access by adding them to the
<filename>/etc/fbtab</filename> file. See <command>man
<filename>/etc/fbtab</filename> file. See <command>man
fbtab</command> for more information.</para>
</note>
@ -1579,7 +1579,7 @@ controller wcd0</programlisting>
<note>
<para>All SCSI controllers use the same set of
<filename>/dev</filename> entries, so you do not need to create
these. Also, network cards and SLIP/PPP pseudo-devices do not
these. Also, network cards and SLIP/PPP pseudo-devices do not
have entries in <filename>/dev</filename> at all, so you do not
have to worry about these either.</para>
</note>
@ -1590,7 +1590,7 @@ controller wcd0</programlisting>
<title>If Something Goes Wrong</title>
<para>There are four categories of trouble that can occur when
building a custom kernel. They are:</para>
building a custom kernel. They are:</para>
<variablelist>
@ -1598,10 +1598,10 @@ controller wcd0</programlisting>
<listitem>
<para>If the <command>config</command> command
fails when you give it your kernel description, you have
probably made a simple error somewhere. Fortunately,
probably made a simple error somewhere. Fortunately,
<command>config</command> will print the line
number that it had trouble with, so you can quickly skip to
it with <command>vi</command>. For example, if
it with <command>vi</command>. For example, if
you see:
@ -1618,7 +1618,7 @@ controller wcd0</programlisting>
<para>If the <command>make</command> command fails,
it usually signals an error in your kernel description, but
not severe enough for <command>config</command>
to catch it. Again, look over your configuration, and if
to catch it. Again, look over your configuration, and if
you still cannot resolve the problem, send mail to the
&a.questions; with your kernel configuration, and it should
be diagnosed very quickly.</para>
@ -1631,17 +1631,17 @@ controller wcd0</programlisting>
<para>If your new kernel does not boot, or fails to recognize
your devices, do not panic! Fortunately, BSD has an
excellent mechanism for recovering from incompatible
kernels. Simply type the name of the kernel you want to boot
kernels. Simply type the name of the kernel you want to boot
from (i.e. <filename>kernel.old</filename>) at the FreeBSD boot prompt
instead of pressing return. When reconfiguring a kernel, it
instead of pressing return. When reconfiguring a kernel, it
is always a good idea to keep a kernel that is known to work
on hand.</para>
<para>After booting with a good kernel you can check over your
configuration file and try to build it again. One helpful
configuration file and try to build it again. One helpful
resource is the <filename>/var/log/messages</filename> file
which records, among other things, all of the kernel
messages from every successful boot. Also, the
messages from every successful boot. Also, the
<citerefentry><refentrytitle>dmesg</refentrytitle><manvolnum>8</manvolnum></citerefentry> command will print the kernel
messages from the current boot.</para>
@ -1649,14 +1649,14 @@ controller wcd0</programlisting>
<para>If you are having trouble building a kernel, make sure
to keep a <filename>GENERIC</filename>, or some other kernel that is known to
work on hand as a different name that will not get erased
on the next build. You cannot rely on
on the next build. You cannot rely on
<filename>kernel.old</filename> because when installing a
new kernel, <filename>kernel.old</filename> is overwritten
with the last installed kernel which may be
non-functional. Also, as soon as possible, move the
non-functional. Also, as soon as possible, move the
working kernel to the proper <filename>kernel</filename> location or
commands such as <citerefentry><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry> will not work
properly. The proper command to &ldquo;unlock&rdquo; the
properly. The proper command to &ldquo;unlock&rdquo; the
kernel file that <command>make</command> installs (in
order to move another kernel back permanently) is:</para>
@ -1684,8 +1684,8 @@ controller wcd0</programlisting>
for example, an experimental &ldquo;2.2.0&rdquo; kernel on a
2.1.0-RELEASE system, many system-status commands like
<citerefentry><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry> and <citerefentry><refentrytitle>vmstat</refentrytitle><manvolnum>8</manvolnum></citerefentry>
will not work any more. You must recompile the <filename>libkvm</filename> library as well as these
utilities. This is one reason it is not normally a good
will not work any more. You must recompile the <filename>libkvm</filename> library as well as these
utilities. This is one reason it is not normally a good
idea to use a different version of the kernel from the rest
of the operating system.</para>
</listitem>

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

@ -8,48 +8,48 @@
<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
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
<citerefentry><refentrytitle>dumpon</refentrytitle><manvolnum>8</manvolnum></citerefentry> command. The best way to use <citerefentry>
<citerefentry><refentrytitle>dumpon</refentrytitle><manvolnum>8</manvolnum></citerefentry> command. The best way to use <citerefentry>
<refentrytitle>dumpon</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry> is to set the <literal>dumpdev</literal> variable in
<filename>/etc/rc.conf</filename>. Typically you want to specify one of
<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
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 <citerefentry><refentrytitle>dumpon</refentrytitle><manvolnum>8</manvolnum></citerefentry> 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
<citerefentry><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry>). This is normally arranged via
<citerefentry><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry>). 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
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
<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
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
called by another name. This feature may well be discontinued in
further releases.</para>
</note>
<para>When the kernel has been built make a copy of it, say
<filename>kernel.debug</filename>, and then run <command>strip
-d</command> on the original. Install the original as normal. You
-d</command> on the original. Install the original as normal. You
may also install the unstripped kernel, but symbol table lookup time
for some programs will drastically increase, and since the whole
kernel is loaded entirely at boot time and cannot be swapped out
@ -69,13 +69,13 @@ Dumps to non-swap devices, tapes for example,
<para>This instructs <citerefentry><refentrytitle>savecore</refentrytitle><manvolnum>8</manvolnum></citerefentry> to
use another kernel for symbol name extraction. It would otherwise
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>
<filename>/sys/compile/WHATEVER</filename> and run <command>kgdb</command>. From <command>kgdb</command>
do:
@ -88,7 +88,7 @@ Dumps to non-swap devices, tapes for example,
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
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>
@ -203,8 +203,8 @@ Dumps to non-swap devices, tapes for example,
<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
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
@ -243,9 +243,9 @@ Dumps to non-swap devices, tapes for example,
<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>
<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>
normally. For example;</para>
<screen>&prompt.root; <userinput>ddd -k /var/crash/kernel.0 /var/crash/vmcore.0</userinput></screen>
@ -260,32 +260,32 @@ Dumps to non-swap devices, tapes for example,
<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>
-g</command>? Not everything is lost here. Do not panic!</para>
<para>Of course, you still need to enable crash dumps. See above on
<para>Of course, you still need to enable crash dumps. See above on
the options you have to specify in order to do this.</para>
<para>Go to your kernel compile directory, and edit the line
containing <literal>COPTFLAGS?=-O</literal>. Add the
containing <literal>COPTFLAGS?=-O</literal>. Add the
<option>-g</option> option there (but <emphasis>do not</emphasis>
change anything on the level of optimization). If you do already
change anything on the level of optimization). If you do already
know roughly the probable location of the failing piece of code
(e.g., the <devicename>pcvt</devicename> driver in the example
above), remove all the object files for this code. Rebuild the
kernel. Due to the time stamp change on the Makefile, there will be
above), remove all the object files for this code. Rebuild the
kernel. Due to the time stamp change on the Makefile, there will be
some other object files rebuild, for example
<filename>trap.o</filename>. With a bit of luck, the added
<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
code to the faulting one but some debugging symbols. You should at
least verify the old and new sizes with the
<citerefentry><refentrytitle>size</refentrytitle><manvolnum>1</manvolnum></citerefentry> command. If there is a mismatch, you
<citerefentry><refentrytitle>size</refentrytitle><manvolnum>1</manvolnum></citerefentry> 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
<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
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>
@ -300,52 +300,52 @@ Dumps to non-swap devices, tapes for example,
<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
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
an on-line debugger available called DDB. It allows to setting
breakpoints, single-steping kernel functions, examining and changing
kernel variables, etc. However, it cannot access kernel source
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
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
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
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
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
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
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
<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>
@ -356,7 +356,7 @@ options DDB</programlisting> to your config file, and rebuild. (See <link
<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
<literal>0x</literal> (this is optional for other numbers). Simple
expressions are allowed, for example: <literal>function-name +
0x103</literal>.</para>
@ -386,7 +386,7 @@ options DDB</programlisting> to your config file, and rebuild. (See <link
<para>The first form will be accepted immediately after
a breakpoint hit, and deletes the current breakpoint. The second
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>
@ -422,8 +422,8 @@ options DDB</programlisting> to your config file, and rebuild. (See <link
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
hexadecimal/decimal/character/ string display. The number after the
comma is the object count. To display the next 0x10 items, simply
use:</para>
@ -487,9 +487,9 @@ options DDB</programlisting> to your config file, and rebuild. (See <link
<para>Now you have now examined why your kernel failed, and you wish
to reboot. Remember that, depending on the severity of previous
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
as expected. Perform one of the following actions to shut down and
reboot your system:</para>
@ -497,8 +497,8 @@ options DDB</programlisting> to your config file, and rebuild. (See <link
<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
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>
@ -507,7 +507,7 @@ options DDB</programlisting> to your config file, and rebuild. (See <link
<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
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>
@ -526,7 +526,7 @@ options DDB</programlisting> to your config file, and rebuild. (See <link
<para>However, it is highly recommended to have a
printed copy of the <citerefentry><refentrytitle>ddb</refentrytitle><manvolnum>4</manvolnum></citerefentry> manual page
ready for a debugging session. Remember that it is hard to read the
ready for a debugging session. Remember that it is hard to read the
on-line manual while single-stepping the kernel.</para>
</sect1>
@ -538,9 +538,9 @@ options DDB</programlisting> to your config file, and rebuild. (See <link
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
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
@ -548,12 +548,12 @@ options DDB</programlisting> to your config file, and rebuild. (See <link
<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
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,
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>
@ -589,8 +589,8 @@ Stopped at Debugger+0x35: movb $0, edata+0x51bc
<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
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>
@ -605,7 +605,7 @@ Debugger (msg=0xf01b0383 "Boot flags requested debugger")
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
<para>Remote GDB can also be used to debug LKMs. First build the LKM
with debugging symbols:</para>
@ -625,8 +625,8 @@ 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
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>
@ -644,10 +644,10 @@ text_addr = 0xf5109020? (y or n) <userinput>y</userinput>
<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
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
onto your first serial port. DDB works on any configured console
driver, of course also on a serial console.</para>
</sect1>

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

@ -14,23 +14,23 @@
<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
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
<citerefentry><refentrytitle>config</refentrytitle><manvolnum>8</manvolnum></citerefentry>, 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
necessary. Wiping out the old compile directory on each run of
<citerefentry><refentrytitle>config</refentrytitle><manvolnum>8</manvolnum></citerefentry> 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
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
overridable by the config option. This is usually done with
something like:</para>
<programlisting>
@ -40,7 +40,7 @@
<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
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>
@ -63,32 +63,32 @@
<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
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>
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
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,
<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
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
of his kernel). Once the transition of all supported options has
been done, <citerefentry><refentrytitle>config</refentrytitle><manvolnum>8</manvolnum></citerefentry> will warn whenever an
unsupported option appears in the config file, but it will
nevertheless include it into the kernel Makefile.</para>
@ -102,19 +102,19 @@ options notyet,notdef</programlisting>
<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
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
<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
<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
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. <citerefentry><refentrytitle>config</refentrytitle><manvolnum>8</manvolnum></citerefentry> will automagically pick up the change, and create that file next time it is run. Most options should go in a header file by themselves..</para>
<filename>options[<replaceable>.&lt;arch&gt;</replaceable>]</filename> file. <citerefentry><refentrytitle>config</refentrytitle><manvolnum>8</manvolnum></citerefentry> 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
@ -129,13 +129,13 @@ options notyet,notdef</programlisting>
<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,
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
<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
@ -152,7 +152,7 @@ options notyet,notdef</programlisting>
<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
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>

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

@ -52,7 +52,7 @@ font8x8=cp866-8x8</programlisting>
key remapped to match Russian <citerefentry><refentrytitle>termcap</refentrytitle><manvolnum>5</manvolnum></citerefentry> entry for FreeBSD
console.</para>
<para>RUS/LAT switch will be <literal>CapsLock</literal>. Old CapsLock function still
<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>
@ -96,7 +96,7 @@ ttyv0 "/usr/libexec/getty Pc" cons25r on secure</programlisting>
<para>The best way is using <filename>/etc/login.conf</filename>
<literal>russian</literal> user's login class in
<citerefentry><refentrytitle>passwd</refentrytitle><manvolnum>5</manvolnum></citerefentry> entry login class
position. See <citerefentry><refentrytitle>login.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
position. See <citerefentry><refentrytitle>login.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
details.</para>
@ -235,8 +235,8 @@ setenv MM_CHARSET KOI8-R</programlisting>
<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
-&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>
@ -282,7 +282,7 @@ lp|Russian local line printer:\
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
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>
@ -295,8 +295,8 @@ lp|Russian local line printer:\
<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
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
@ -323,7 +323,7 @@ XkbKeymap "xfree86(ru)"</programlisting> line into
<literal>XkbDisable</literal> is turned off
(commented out) there.</para>
<para>RUS/LAT switch will be <literal>CapsLock</literal>. Old CapsLock function still
<para>RUS/LAT switch will be <literal>CapsLock</literal>. Old CapsLock function still
available via <literal>Shift+CapsLock</literal>
(in LAT mode only).</para>
@ -346,7 +346,7 @@ XkbKeymap "xfree86(ru)"</programlisting> line into
<sect1 id="german">
<title>German Language (ISO 8859-1)</title>
<para>Slaven Rezic <email>eserte@cs.tu-berlin.de</email> wrote a tutorial how to use umlauts on a FreeBSD machine. The tutorial is written in German and available at <ulink URL="http://www.de.freebsd.org/de/umlaute/">http://www.de.freebsd.org/de/umlaute/</ulink>.</para>
<para>Slaven Rezic <email>eserte@cs.tu-berlin.de</email> wrote a tutorial how to use umlauts on a FreeBSD machine. The tutorial is written in German and available at <ulink URL="http://www.de.freebsd.org/de/umlaute/">http://www.de.freebsd.org/de/umlaute/</ulink>.</para>
</sect1>
</chapter>

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

@ -9,14 +9,14 @@
<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
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
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
@ -31,8 +31,8 @@
<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 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>
@ -50,7 +50,7 @@ options COMPAT_LINUX</programlisting>
options SYSVSHM</programlisting>
<para>The linux system calls require 4.3BSD system
call compatibility. So make sure you have the following.</para>
call compatibility. So make sure you have the following.</para>
<programlisting>
options "COMPAT_43"</programlisting>
@ -67,7 +67,7 @@ options LINUX</programlisting>
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. 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>
@ -95,11 +95,11 @@ 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
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
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>
@ -112,9 +112,9 @@ linux</programlisting>
<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
<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
without having to reboot. You will need the following things in
your startup files, however:</para>
<orderedlist>
@ -149,14 +149,14 @@ 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
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
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>
@ -170,7 +170,7 @@ options LINUX</programlisting>
<title>Installing using the linux_lib port</title>
<para>Most linux applications use shared libraries, so you are
still not done until you install the shared libraries. It is
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_lib port:</para>
@ -179,12 +179,12 @@ options LINUX</programlisting>
&prompt.root; <userinput>make all install</userinput></screen>
<para>and you should have a working linux emulator. Legend (and
<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
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>
@ -194,17 +194,17 @@ options LINUX</programlisting>
<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
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"
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
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,
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
<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>
@ -216,7 +216,7 @@ options LINUX</programlisting>
<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,
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>
@ -235,7 +235,7 @@ options LINUX</programlisting>
<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
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>
@ -266,9 +266,9 @@ libc.so.4 (DLL Jump 4.5pl26) =&gt; /lib/libc.so.4.6.29</screen>
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,
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>
@ -299,7 +299,7 @@ libc.so.4 (DLL Jump 4.5pl26) =&gt; /lib/libc.so.4.6.29</screen>
<note>
<para>The symbolic link mechanism is <emphasis>only</emphasis>
needed for Linux binaries. The FreeBSD runtime linker takes
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>
@ -314,7 +314,7 @@ libc.so.4 (DLL Jump 4.5pl26) =&gt; /lib/libc.so.4.6.29</screen>
<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
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>
@ -324,8 +324,8 @@ libc.so.4 (DLL Jump 4.5pl26) =&gt; /lib/libc.so.4.6.29</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,
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
@ -343,16 +343,16 @@ libc.so.4 (DLL Jump 4.5pl26) =&gt; /lib/libc.so.4.6.29</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
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
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>
@ -362,7 +362,7 @@ libc.so.4 (DLL Jump 4.5pl26) =&gt; /lib/libc.so.4.6.29</screen>
<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
<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.)
@ -378,7 +378,7 @@ libc.so.4 (DLL Jump 4.5pl26) =&gt; /lib/libc.so.4.6.29</screen>
<para><command>ldconfig</command> is statically linked, so it does not need any
shared libraries to run. It creates the file
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
@ -390,8 +390,8 @@ libc.so.4 (DLL Jump 4.5pl26) =&gt; /lib/libc.so.4.6.29</screen>
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
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>
@ -400,19 +400,19 @@ 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
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 <citerefentry><refentrytitle>ldd</refentrytitle><manvolnum>1</manvolnum></citerefentry>)
and watch its output. <command>ldd</command> (see also the manual page for <citerefentry><refentrytitle>ldd</refentrytitle><manvolnum>1</manvolnum></citerefentry>)
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
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)
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>
@ -423,7 +423,7 @@ libc.so.4 (DLL Jump 4.5pl26) =&gt; /lib/libc.so.4.6.29</screen>
<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,
&ldquo;branding&rdquo;. If you attempt to run an unbranded ELF binary,
you will get an error message like the following;</para>
@ -466,18 +466,18 @@ multi on</programlisting>
where the order here specifies that
<filename>/etc/hosts</filename> is searched first and DNS is
searched second. When
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
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
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>
@ -503,12 +503,12 @@ multi on</programlisting>
</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,
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
with gzipped tar files in them. The primary ftp sites for the
distributions are:</para>
<orderedlist>
@ -538,15 +538,15 @@ multi on</programlisting>
</orderedlist>
<para>For simplicity, let us concentrate on Slackware here. This
<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,
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
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
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>
@ -585,10 +585,10 @@ multi on</programlisting>
</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
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
us in which subdirectory we need to look. For our example, we
would find the following locations:</para>
<informaltable frame="none">
@ -611,7 +611,7 @@ multi on</programlisting>
<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
<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>
@ -655,13 +655,13 @@ multi on</programlisting>
<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
<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
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>
@ -670,8 +670,8 @@ multi on</programlisting>
<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
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>
@ -703,14 +703,14 @@ 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
<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
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>
@ -722,21 +722,21 @@ richc.isdn.bcm.tmc.edu 9845-03452-90255</screen>
<para>It will ask you to enter your license number
and the Wolfram supplied password. If you get them mixed up or
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.
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
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
program. The directories we chose to create beforehand and
specify to <command>math.install</command> were:</para>
<informaltable frame="none">
@ -762,23 +762,23 @@ richc.isdn.bcm.tmc.edu 9845-03452-90255</screen>
<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
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
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
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
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
Mathematica has installed. At the beginning of every shell script
in <filename>/usr/local/Mathematica/bin</filename> add the
following line:</para>
@ -798,7 +798,7 @@ richc.isdn.bcm.tmc.edu 9845-03452-90255</screen>
<para>This tells Mathematica to use the linux version
of host.conf. This file has a different syntax from FreeBSD's
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>
@ -809,11 +809,11 @@ richc.isdn.bcm.tmc.edu 9845-03452-90255</screen>
<filename>/usr/local/Mathematica/bin</filename> to your
path.</para>
<para>That is about all it takes. With this you should be able to
<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
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>
the Motif libraries. Good luck doing this yourself!</para>
</sect2>

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

@ -37,7 +37,7 @@
on static lists of hosts.</para>
<para>Additionally, FreeBSD is available via anonymous FTP from the
following mirror sites. If you choose to obtain FreeBSD via
following mirror sites. If you choose to obtain FreeBSD via
anonymous FTP, please try to use a site near you.</para>
<para><link linkend="mirrors-ar">Argentina</link>,
@ -831,7 +831,7 @@
<para>The latest versions of export-restricted code for FreeBSD (2.0C
or later) (eBones and secure) are being made available at the
following locations. If you are outside the U.S. or Canada, please
following locations. If you are outside the U.S. or Canada, please
get secure (DES) and eBones (Kerberos) from one of the following
foreign distribution sites:</para>
@ -902,7 +902,7 @@
<title>CTM Sites</title>
<para><link linkend="ctm">CTM</link>/FreeBSD is available via
anonymous FTP from the following mirror sites. If you choose to
anonymous FTP from the following mirror sites. If you choose to
obtain CTM via anonymous FTP, please try to use a site near
you.</para>
@ -989,7 +989,7 @@
<para>If you did not find a mirror near to you or the mirror is
incomplete, try <ulink URL="http://ftpsearch.ntnu.no/">FTP
search</ulink> at <ulink
URL="http://ftpsearch.ntnu.no/ftpsearch/">http://ftpsearch.ntnu.no/ftpsearch</ulink>. FTP search is a great free archie server in Trondheim, Norway.</para>
URL="http://ftpsearch.ntnu.no/ftpsearch/">http://ftpsearch.ntnu.no/ftpsearch</ulink>. FTP search is a great free archie server in Trondheim, Norway.</para>
</sect1>
@ -1379,18 +1379,18 @@
<para>The following <application>CVSup</application> site is especially designed for <link
linkend="ctm">CTM</link> users. Unlike the other CVSup mirrors,
it is kept up-to-date by <application>CTM</application>. That means if you <application>CVSup</application> <literal>cvs-all</literal> with <literal>release=cvs</literal>
linkend="ctm">CTM</link> users. Unlike the other CVSup mirrors,
it is kept up-to-date by <application>CTM</application>. That means if you <application>CVSup</application> <literal>cvs-all</literal> with <literal>release=cvs</literal>
from this site, you get a version of the repository (including the
inevitable <filename>.ctm_status</filename> file) which is
suitable for being updated using the <application>CTM</application> <literal>cvs-cur</literal> deltas. This allows users who track
suitable for being updated using the <application>CTM</application> <literal>cvs-cur</literal> deltas. This allows users who track
the entire <literal>cvs-all</literal> tree to go from
<application>CVSup</application> to <application>CTM</application> without having to rebuild their repository from scratch
using a fresh <application>CTM</application> base delta.</para>
<note>
<para>This special feature only works for the <literal>cvs-all</literal> distribution with
<command>cvs</command> as the release tag. CVSupping any other
<command>cvs</command> as the release tag. CVSupping any other
distribution and/or release will get you the specified
distribution, but it will not be suitable for <application>CTM</application> updating.</para>
</note>
@ -1398,8 +1398,8 @@
<note>
<para>Because the current version of <application>CTM</application> does not preserve the
timestamps of files, the timestamps at this mirror site are not
the same as those at other mirror sites. Switching between this
site and other sites is not recommended. It will work correctly,
the same as those at other mirror sites. Switching between this
site and other sites is not recommended. It will work correctly,
but will be somewhat inefficient.</para>
</note>

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

@ -2,7 +2,7 @@
<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
one of the officers or core team members a number of keys are
provided here for your convenience.</para>

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

@ -24,22 +24,22 @@ MAINTAINER= email-addresses</programlisting>
<para>The semantics of this are as follows:</para>
<para>The maintainer owns and is responsible for that code. This
<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
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
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
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>
@ -48,44 +48,44 @@ MAINTAINER= email-addresses</programlisting>
<sect1>
<title>Contributed Software</title>
<para><emphasis>Contributed by &a.phk; and &a.obrien;. </emphasis></para>
<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
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>
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>
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
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
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
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
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
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
revision 1.1.x.x. The repository bloat impact from a single character
change can be rather dramatic.</para>
</note>
@ -93,8 +93,8 @@ MAINTAINER= email-addresses</programlisting>
language will be used as example of how this model works:</para>
<para><filename>src/contrib/tcl</filename> contains the source as
distributed by the maintainers of this package. Parts that are
entirely not applicable for FreeBSD can be removed. In the case of
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>
@ -111,23 +111,23 @@ MAINTAINER= email-addresses</programlisting>
<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
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
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
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
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
@ -136,7 +136,7 @@ MAINTAINER= email-addresses</programlisting>
<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
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>
@ -144,7 +144,7 @@ MAINTAINER= email-addresses</programlisting>
<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
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>
@ -180,14 +180,14 @@ MAINTAINER= email-addresses</programlisting>
<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
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
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:
@ -233,7 +233,7 @@ obrien@freebsd.org - 30 March 1997</programlisting>
<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
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>
@ -260,14 +260,14 @@ obrien@freebsd.org - 30 March 1997</programlisting>
<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
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
<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
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
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
@ -276,14 +276,14 @@ obrien@freebsd.org - 30 March 1997</programlisting>
<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>
&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
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

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

File diff suppressed because it is too large Load diff

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

@ -3,9 +3,9 @@
<para>If your connection to the Internet is through a modem, or you wish
to provide other people with dialup connections to the Internet using
FreeBSD, you have the option of using PPP or SLIP. Furthermore, two
FreeBSD, you have the option of using PPP or SLIP. Furthermore, two
varieties of PPP are provided: <emphasis>user</emphasis> (sometimes
referred to as <emphasis>iijppp</emphasis>) and <emphasis>kernel</emphasis>. The
referred to as <emphasis>iijppp</emphasis>) and <emphasis>kernel</emphasis>. The
procedures for configuring both types of PPP, and for setting up SLIP
are described in this chapter.</para>
@ -14,33 +14,33 @@
<title>Setting up User PPP</title>
<para>User PPP was introduced to FreeBSD in release 2.0.5 as an
addition to the existing kernel implementation of PPP. So, what is
addition to the existing kernel implementation of PPP. So, what is
different about this new PPP that warrants its addition? To quote
from the manual page:</para>
<blockquote>
<para>This is a user process PPP software package. Normally, PPP
<para>This is a user process PPP software package. Normally, PPP
is implemented as a part of the kernel (e.g. as managed by <command>pppd</command>)
and it is thus somewhat hard to debug and/or modify its
behavior. However, in this implementation PPP is done as a user
behavior. However, in this implementation PPP is done as a user
process with the help of the tunnel device driver (tun).</para>
</blockquote>
<para>In essence, this means that rather than running a PPP daemon,
the ppp program can be run as and when desired. No PPP interface
the ppp program can be run as and when desired. No PPP interface
needs to be compiled into the kernel, as the program can use the
generic tunnel device to get data into and out of the kernel.</para>
<para>From here on out, user ppp will be referred to simply as ppp
unless a distinction needs to be made between it and any other PPP
client/server software such as <command>pppd</command>. Unless otherwise stated, all
client/server software such as <command>pppd</command>. Unless otherwise stated, all
commands in this section should be executed as root.</para>
<para>There are a large number of enhancements in version 2 of ppp. You
<para>There are a large number of enhancements in version 2 of ppp. You
can discover what version you have by running ppp with no arguments
and typing <command>show version</command> at the prompt. It is a
and typing <command>show version</command> at the prompt. It is a
simple matter to upgrade to the latest version of ppp (under any
version of FreeBSD) by downloading the latest archive via <ulink
url="http://www.Awfulhak.org/ppp.html">www.Awfulhak.org</ulink>.</para>
@ -51,7 +51,7 @@
<para>This document assumes you are in roughly this position:</para>
<para>You have an account with an Internet Service Provider (ISP)
which lets you use PPP. Further, you have a modem (or other
which lets you use PPP. Further, you have a modem (or other
device) connected and configured correctly which allows you to
connect to your ISP.</para>
@ -66,19 +66,19 @@
</listitem>
<listitem>
<para>Your login name and password. This can be either a
<para>Your login name and password. This can be either a
regular unix style login/password pair, or a PPP PAP or CHAP
login/password pair.</para>
</listitem>
<listitem>
<para>The IP addresses of one or more nameservers. Normally,
you will be given two IP numbers. You
<para>The IP addresses of one or more nameservers. Normally,
you will be given two IP numbers. You
<emphasis>must</emphasis> have this information for
<application>PPP</application> version 1.x unless you run
your own nameserver. From version 2 onwards,
your own nameserver. From version 2 onwards,
<application>PPP</application> supports nameserver address
negotiation. If your ISP supports this, then using the command
negotiation. If your ISP supports this, then using the command
<command>enable dns</command> in your config file will tell
<application>PPP</application> to set the nameservers for
you.</para>
@ -92,7 +92,7 @@
<listitem>
<para>The IP address of your ISP's gateway. The gateway is the
machine to which you will connect and will be set up as your
<emphasis>default route</emphasis>. If your ISP hasn't given
<emphasis>default route</emphasis>. If your ISP hasn't given
you this number, we can make one up and your ISP's PPP server
will tell us the correct value when we connect.</para>
@ -101,12 +101,12 @@
</listitem>
<listitem>
<para>Your ISP's netmask. If your ISP hasn't given you this
<para>Your ISP's netmask. If your ISP hasn't given you this
information, you can safely use a netmask of <hostid
role="netmask">255.255.255.0</hostid>.</para>
<para>If your ISP allocates you a static IP address and hostname
then you can enter this information. Otherwise, we simply let the
then you can enter this information. Otherwise, we simply let the
peer assign whatever IP number it sees fit.</para>
</listitem>
</itemizedlist>
@ -120,18 +120,18 @@
<title>Building a ppp ready kernel</title>
<para>As the description states, <command>ppp</command> uses the kernel <devicename>tun</devicename>
device. It is necessary to make sure that your kernel has support
device. It is necessary to make sure that your kernel has support
for this device compiled in.</para>
<para>To check this, go to your kernel compile directory
(<filename>/sys/i386/conf</filename> or
<filename>/sys/pc98/conf</filename>) and examine your kernel
configuration file. It needs to have the line
configuration file. It needs to have the line
<programlisting>
pseudo-device tun 1</programlisting>
in it somewhere. The stock <filename>GENERIC</filename> kernel
in it somewhere. The stock <filename>GENERIC</filename> kernel
has this as standard, so if you have not installed a custom kernel
or you do not have a <filename>/sys</filename> directory, you do not have to change
anything.</para>
@ -141,7 +141,7 @@ pseudo-device tun 1</programlisting>
example, if you are setting up a server and could have 16 dialup
ppp connections at any one time then you will need to use <literal>16</literal>
instead of <literal>1</literal>), then you should add the line, re-compile,
re-install and boot the new kernel. Please refer to the
re-install and boot the new kernel. Please refer to the
<link linkend="kernelconfig">Configuring the FreeBSD
Kernel</link> section for more information on kernel
configuration.</para>
@ -161,32 +161,32 @@ tun3: flags=8010&lt;POINTOPOINT,MULTICAST&gt; mtu 1500</screen>
<para>This case shows four tunnel devices, two of which are
currently configured and being used. It should be noted that the
currently configured and being used. It should be noted that the
<literal>RUNNING</literal> flag above indicates that the interface has
been used at some point&mdash;it is not an error if your interface does
not show up as <literal>RUNNING</literal>.</para>
<para>If you have a kernel without the tun device, and you can not
rebuild it for some reason, all is not lost. You should be able
to dynamically load the code. Refer to the appropriate <citerefentry><refentrytitle>modload</refentrytitle><manvolnum>8</manvolnum></citerefentry>
rebuild it for some reason, all is not lost. You should be able
to dynamically load the code. Refer to the appropriate <citerefentry><refentrytitle>modload</refentrytitle><manvolnum>8</manvolnum></citerefentry>
and <citerefentry><refentrytitle>lkm</refentrytitle><manvolnum>4</manvolnum></citerefentry> pages for further details.</para>
<para>You may also wish to take this opportunity to configure a
firewall. Details can be found in the <link linkend="firewalls">Firewalls</link> section.</para>
firewall. Details can be found in the <link linkend="firewalls">Firewalls</link> section.</para>
</sect2>
<sect2>
<title>Check the tun device</title>
<para>Most users will only require one <devicename>tun</devicename> device (<filename>/dev/tun0</filename>). If you
<para>Most users will only require one <devicename>tun</devicename> device (<filename>/dev/tun0</filename>). If you
have used more (i.e., a number other than <literal>1</literal> in the <literal>pseudo-device</literal>
line in the kernel configuration file) then alter all references
to <devicename>tun0</devicename> below to reflect whichever device number you are
using.</para>
<para>The easiest way to make sure that the <devicename>tun0</devicename> device is
configured correctly is to re-make it. To do this, execute the
configured correctly is to re-make it. To do this, execute the
following commands:</para>
@ -226,10 +226,10 @@ tun0: flags=8010&lt;POINTOPOINT,MULTICAST> mtu 1500</screen>
<title>Name Resolution Configuration</title>
<para>The resolver is the part of the system that turns IP addresses
into hostnames and vice versa. It can be configured to look for
into hostnames and vice versa. It can be configured to look for
maps that describe IP to hostname mappings in one of two places.
The first is a file called <filename>/etc/hosts</filename>
(<command>man 5 hosts</command>). The second is the
(<command>man 5 hosts</command>). The second is the
Internet Domain Name Service (DNS), a distributed data base, the
discussion of which is beyond the scope of this document.</para>
@ -238,8 +238,8 @@ tun0: flags=8010&lt;POINTOPOINT,MULTICAST> mtu 1500</screen>
<para>The resolver is a set of system calls that do the name
mappings, but you have to tell them where to find their
information. You do this by first editing the file
<filename>/etc/host.conf</filename>. Do <emphasis>not</emphasis> call this file
information. You do this by first editing the file
<filename>/etc/host.conf</filename>. Do <emphasis>not</emphasis> call this file
<filename>/etc/hosts.conf</filename> (note the extra <literal>s</literal>) as the
results can be confusing.</para>
@ -265,8 +265,8 @@ bind</programlisting>
<title>Edit the <filename>/etc/hosts</filename>(5) file</title>
<para>This file should contain the IP addresses and names of
machines on your network. At a bare minimum it should contain
entries for the machine which will be running ppp. Assuming that
machines on your network. At a bare minimum it should contain
entries for the machine which will be running ppp. Assuming that
your machine is called <hostid role="fqdn">foo.bar.com</hostid>
with the IP address <hostid role="ipaddr">10.0.0.1</hostid>,
<filename>/etc/hosts</filename> should contain:</para>
@ -276,8 +276,8 @@ bind</programlisting>
10.0.0.1 foo.bar.com foo</programlisting>
<para>The first line defines the alias <hostid>localhost</hostid> as a synonym
for the current machine. Regardless of your own IP address, the
IP address for this line should always be <hostid role="ipaddr">127.0.0.1</hostid>. The second
for the current machine. Regardless of your own IP address, the
IP address for this line should always be <hostid role="ipaddr">127.0.0.1</hostid>. The second
line maps the name <hostid role="fqdn">foo.bar.com</hostid> (and the shorthand <hostid>foo</hostid>)
to the IP address <hostid role="ipaddr">10.0.0.1</hostid>.</para>
@ -290,8 +290,8 @@ bind</programlisting>
<title>Edit the <filename>/etc/resolv.conf</filename> file</title>
<para><filename>/etc/resolv.conf</filename> tells the resolver how
to behave. If you are running your own DNS, you may leave this
file empty. Normally, you will need to enter the following
to behave. If you are running your own DNS, you may leave this
file empty. Normally, you will need to enter the following
line(s):</para>
<programlisting>
@ -302,15 +302,15 @@ domain <replaceable>bar.com</replaceable></programlisting>
<para>The <hostid
role="ipaddr"><replaceable>x.x.x.x</replaceable></hostid> and
<hostid role="ipaddr"><replaceable>y.y.y.y</replaceable></hostid> addresses are those given to you
by your ISP. Add as many <literal>nameserver</literal> lines as your ISP
provides. The <literal>domain</literal> line defaults to your hostname's
domain, and is probably unnecessary. Refer to the <filename>resolv.conf</filename>
by your ISP. Add as many <literal>nameserver</literal> lines as your ISP
provides. The <literal>domain</literal> line defaults to your hostname's
domain, and is probably unnecessary. Refer to the <filename>resolv.conf</filename>
manual page for details of other possible entries in this
file.</para>
<para>If you are running PPP version 2 or greater, the <command>enable
dns</command> command will tell PPP to request that your ISP
confirms the nameserver values. If your ISP supplies different
confirms the nameserver values. If your ISP supplies different
addresses (or if there are no nameserver lines in
<filename>/etc/resolv.conf</filename>), PPP will rewrite the file
with the ISP-supplied values.</para>
@ -322,12 +322,12 @@ domain <replaceable>bar.com</replaceable></programlisting>
<para>Both user ppp and <command>pppd</command> (the kernel level implementation of
PPP) use configuration files located in the
<filename>/etc/ppp</filename> directory. The sample configuration
<filename>/etc/ppp</filename> directory. The sample configuration
files provided are a good reference for user ppp, so don't delete
them.</para>
<para>Configuring <command>ppp</command> requires that you edit a number of files,
depending on your requirements. What you put in them depends to
depending on your requirements. What you put in them depends to
some extent on whether your ISP allocates IP addresses statically
(i.e., you get given one IP address, and always use that one) or
dynamically (i.e., your IP address can be different for each PPP
@ -338,7 +338,7 @@ domain <replaceable>bar.com</replaceable></programlisting>
<title>PPP and Static IP addresses</title>
<para>You will need to create a configuration file called
<filename>/etc/ppp/ppp.conf</filename>. It should look similar
<filename>/etc/ppp/ppp.conf</filename>. It should look similar
to the example below.</para>
<note>
@ -368,7 +368,7 @@ domain <replaceable>bar.com</replaceable></programlisting>
<variablelist>
<varlistentry><term>Line 1:</term>
<listitem>
<para>Identifies the default entry. Commands in this
<para>Identifies the default entry. Commands in this
entry are executed automatically when ppp is run.</para>
</listitem>
</varlistentry>
@ -377,7 +377,7 @@ domain <replaceable>bar.com</replaceable></programlisting>
<listitem>
<para>Identifies the device to which the modem is
connected. <devicename>COM1:</devicename> is <filename>/dev/cuaa0</filename> and
connected. <devicename>COM1:</devicename> is <filename>/dev/cuaa0</filename> and
<devicename>COM2:</devicename> is <filename>/dev/cuaa1</filename>.</para>
</listitem>
</varlistentry>
@ -385,7 +385,7 @@ domain <replaceable>bar.com</replaceable></programlisting>
<varlistentry><term>Line 3:</term>
<listitem>
<para>Sets the speed you want to connect at. If 115200
<para>Sets the speed you want to connect at. If 115200
doesn't work (it should with any reasonably new modem),
try 38400 instead.</para>
</listitem>
@ -394,9 +394,9 @@ domain <replaceable>bar.com</replaceable></programlisting>
<varlistentry><term>Line 4:</term>
<listitem>
<para>The dial string. User PPP uses an expect-send
<para>The dial string. User PPP uses an expect-send
syntax similar to the <citerefentry><refentrytitle>chat</refentrytitle><manvolnum>8</manvolnum></citerefentry>
program. Refer to the manual page for information on
program. Refer to the manual page for information on
the features of this language.</para>
</listitem>
</varlistentry>
@ -412,15 +412,15 @@ domain <replaceable>bar.com</replaceable></programlisting>
<varlistentry><term>Line 6:</term>
<listitem>
<para>Sets the phone number for this provider. Multiple
<para>Sets the phone number for this provider. Multiple
phone numbers may be specified using the
<literal>:</literal> or <literal>|</literal>
character as a separator. The difference between these
spearators is described in the ppp manual page. To
character as a separator. The difference between these
spearators is described in the ppp manual page. To
summarize, if you want to rotate through the numbers,
use the <literal>:</literal>. If you want to always attempt to dial
use the <literal>:</literal>. If you want to always attempt to dial
the first number first and only use the other numbers if
the first number fails, use the <literal>|</literal>. Always quote the
the first number fails, use the <literal>|</literal>. Always quote the
entire set of phone numbers as shown.</para>
</listitem>
</varlistentry>
@ -429,7 +429,7 @@ domain <replaceable>bar.com</replaceable></programlisting>
<listitem>
<para>The login string is of the same chat-like syntax as
the dial string. In this example, the string works for
the dial string. In this example, the string works for
a service whose login session looks like this:</para>
@ -441,13 +441,13 @@ protocol: ppp</screen>
<para>You will need to alter this script to suit your own
needs. When you write this script for the first time,
needs. When you write this script for the first time,
you should enable &ldquo;chat&rdquo; logging to ensure that
the conversation is going as expected.</para>
<para>If you're using PAP or CHAP, there will be no
login at this point, so your login string can be left
blank. See
blank. See
<link linkend="userppp-PAPnCHAP">PAP and CHAP
authentication</link> for further details.</para>
</listitem>
@ -457,8 +457,8 @@ protocol: ppp</screen>
<listitem>
<para>Sets the default timeout (in seconds) for the
connection. Here, the connection will be closed
automatically after 300 seconds of inactivity. If you
connection. Here, the connection will be closed
automatically after 300 seconds of inactivity. If you
never want to timeout, set this value to zero.</para>
</listitem>
</varlistentry>
@ -466,18 +466,18 @@ protocol: ppp</screen>
<varlistentry><term>Line 9:</term>
<listitem>
<para>Sets the interface addresses. The string <replaceable>x.x.x.x</replaceable>
<para>Sets the interface addresses. The string <replaceable>x.x.x.x</replaceable>
should be replaced by the IP address that your provider
has allocated to you. The string <replaceable>y.y.y.y</replaceable> should be
has allocated to you. The string <replaceable>y.y.y.y</replaceable> should be
replaced by the IP address that your ISP indicated for
their gateway (the machine to which you connect). If
their gateway (the machine to which you connect). If
your ISP hasn't given you a gateway address, use
<hostid role="netmask">10.0.0.2/0</hostid>. If you need
<hostid role="netmask">10.0.0.2/0</hostid>. If you need
to use a &ldquo;guessed&rdquo; address, make sure that you create
an entry in <filename>/etc/ppp/ppp.linkup</filename> as
per the instructions for
<link linkend="userppp-dynamicIP">PPP and Dynamic
IP addresses</link>. If this line is omitted, <command>ppp</command> cannot
IP addresses</link>. If this line is omitted, <command>ppp</command> cannot
run in <option>-auto</option> or
<option>-dynamic</option> mode.</para>
</listitem>
@ -486,9 +486,9 @@ protocol: ppp</screen>
<varlistentry><term>Line 10:</term>
<listitem>
<para>Adds a default route to your ISPs gateway. The
<para>Adds a default route to your ISPs gateway. The
special word <literal>HISADDR</literal> is replaced with
the gateway address specified on line 9. It is
the gateway address specified on line 9. It is
important that this line appears after line 9, otherwise
<literal>HISADDR</literal> will not yet be
initialized.</para>
@ -501,7 +501,7 @@ protocol: ppp</screen>
<listitem>
<para>This line tells PPP to ask your ISP to confirm that your
nameserver addresses are correct. If your ISP supports this
nameserver addresses are correct. If your ISP supports this
facility, PPP can then update
<filename>/etc/resolv.conf</filename> with the correct
nameserver entries.</para>
@ -512,8 +512,8 @@ protocol: ppp</screen>
<para>It is not necessary to add an entry to
<filename>ppp.linkup</filename> when you have a static IP
address as your routing table entries are already correct before
you connect. You may however wish to create an entry to invoke
programs after connection. This is explained later with the
you connect. You may however wish to create an entry to invoke
programs after connection. This is explained later with the
sendmail example.</para>
<para>Example configuration files can be found in the
@ -526,9 +526,9 @@ protocol: ppp</screen>
<para>If your service provider does not assign static IP numbers,
<command>ppp</command> can be configured to negotiate
the local and remote addresses. This is done by &ldquo;guessing&rdquo; an
the local and remote addresses. This is done by &ldquo;guessing&rdquo; an
IP number and allowing <command>ppp</command> to set it up correctly using the IP
Configuration Protocol (IPCP) after connecting. The
Configuration Protocol (IPCP) after connecting. The
<filename>ppp.conf</filename> configuration is the same as <link
linkend="userppp-staticIP">PPP and
Static IP addresses</link>, with the following change:</para>
@ -537,7 +537,7 @@ protocol: ppp</screen>
9 set ifaddr 10.0.0.1/0 10.0.0.2/0 255.255.255.0</programlisting>
<para>Again, do not include the line numbers, they are just for
reference in this discussion. Indentation of at least one space
reference in this discussion. Indentation of at least one space
is required.</para>
@ -545,7 +545,7 @@ protocol: ppp</screen>
<varlistentry><term>Line 9:</term>
<listitem>
<para>The number after the <literal>/</literal> character is the number
of bits of the address that ppp will insist on. You may
of bits of the address that ppp will insist on. You may
wish to use IP numbers more appropriate to your
circumstances, but the above example will always
work.</para>
@ -553,7 +553,7 @@ protocol: ppp</screen>
<para>The last argument (<literal>0.0.0.0</literal>) tells PPP
to negotiate using address <hostid
role="ipaddr">0.0.0.0</hostid> rather than <hostid
role="ipaddr">10.0.0.1</hostid>. Do not use
role="ipaddr">10.0.0.1</hostid>. Do not use
<literal>0.0.0.0</literal> as the first argument to
<command>set ifaddr</command> as it prevents PPP from setting
up an intial route in <option>-auto</option> mode.</para>
@ -566,7 +566,7 @@ protocol: ppp</screen>
<para>If you are running version 1.x of PPP, uou will also need to create an entry in
<filename>/etc/ppp/ppp.linkup</filename>.
<filename>ppp.linkup</filename> is used after a connection has
been established. At this point, <command>ppp</command> will know what IP
been established. At this point, <command>ppp</command> will know what IP
addresses should <emphasis>really</emphasis> be used.
The following entry will delete the existing bogus routes, and
create correct ones:</para>
@ -583,9 +583,9 @@ protocol: ppp</screen>
<para>On establishing a connection, <command>ppp</command> will look for an
entry in <filename>ppp.linkup</filename> according to
the following rules: First, try to match the same label
as we used in <filename>ppp.conf</filename>. If that
as we used in <filename>ppp.conf</filename>. If that
fails, look for an entry for the IP number of our
gateway. This entry is a four-octet IP style label. If
gateway. This entry is a four-octet IP style label. If
we still haven't found an entry, look for the
<literal>MYADDR</literal> entry.</para>
</listitem>
@ -618,12 +618,12 @@ protocol: ppp</screen>
<filename>/etc/ppp/ppp.linkup.sample</filename> for a detailed
example.</para>
<para>Version 2 of PPP introduces &ldquo;sticky routes&rdquo;. Any
<para>Version 2 of PPP introduces &ldquo;sticky routes&rdquo;. Any
<literal>add</literal> or <literal>delete</literal> lines that
contain <literal>MYADDR</literal> or <literal>HISADDR</literal> will
be remembered, and any time the actual values of
<literal>MYADDR</literal> or <literal>HISADDR</literal> change, the
routes will be re-applied. This removes the necessity of repeating
routes will be re-applied. This removes the necessity of repeating
these lines in <filename>ppp.linkup</filename>.</para>
</sect3>
@ -635,13 +635,13 @@ protocol: ppp</screen>
<para>When you configure <command>ppp</command> to
receive incoming calls on a machine connected to a LAN, you must decide if you wish to
forward packets to the LAN. If you do, you should allocate the
forward packets to the LAN. If you do, you should allocate the
peer an IP number from your LAN's subet, and use the command
<programlisting>
enable proxy</programlisting>
in your <filename>ppp.conf</filename> file. You should also
in your <filename>ppp.conf</filename> file. You should also
confirm that the <filename>/etc/rc.conf</filename> file (this file
used to be called <filename>/etc/sysconfig</filename>) contains the
following:</para>
@ -676,7 +676,7 @@ gateway=YES</programlisting>
<sect4>
<title>PPP permissions</title>
<para><command>ppp</command> must normally be run as user id 0. If however you
<para><command>ppp</command> must normally be run as user id 0. If however you
wish to allow <command>ppp</command> to run in server mode as a normal user by
executing <command>ppp</command> as described below, that user must be given
permission to run <command>ppp</command> by adding them to the
@ -716,7 +716,7 @@ echo "Starting PPP for $IDENT"
exec /usr/sbin/ppp -direct $IDENT</programlisting>
<para>This script should be executable. Now make a symbolic
<para>This script should be executable. Now make a symbolic
link called <filename>ppp-dialup</filename> to this script
using the following commands:</para>
@ -727,7 +727,7 @@ exec /usr/sbin/ppp -direct $IDENT</programlisting>
<para>You should use this script as the
<emphasis>shell</emphasis> for all your dialup ppp users.
This is an example from <filename>/etc/password</filename> for
a dialup PPP user with username <username>pchilds</username>. (remember don't
a dialup PPP user with username <username>pchilds</username>. (remember don't
directly edit the password file, use <command>vipw</command>)</para>
<programlisting>
@ -766,7 +766,7 @@ pchilds:*:1011:300:Peter Childs PPP:/home/ppp:/etc/ppp/ppp-dialup</programlistin
<para>Each of these users dialup accounts should have their
shell set to the symbolic link created above. (ie. <username>mary</username>'s
shell set to the symbolic link created above. (ie. <username>mary</username>'s
shell should be
<filename>/etc/ppp/ppp-mary</filename>).</para>
@ -796,9 +796,9 @@ ttyd1:
</note>
<para>The <literal>default:</literal> section is
loaded for each session. For each dialup line enabled in
loaded for each session. For each dialup line enabled in
<filename>/etc/ttys</filename> create an entry similar to the
one for <literal>ttyd0:</literal> above. Each line
one for <literal>ttyd0:</literal> above. Each line
should get a unique IP address from your pool of IP addresses for
dynamic users.</para>
@ -809,7 +809,7 @@ ttyd1:
<para>Along with the contents of the sample
<filename>/etc/ppp/ppp.conf</filename> above you should add a
section for each of the statically assigned dialup users. We
section for each of the statically assigned dialup users. We
will continue with our <username>fred</username>, <username>sam</username>, and <username>mary</username> example.</para>
<programlisting>
@ -824,7 +824,7 @@ mary:
<para>The file <filename>/etc/ppp/ppp.linkup</filename> should
also contain routing information for each static IP user if
required. The line below would add a route for the <hostid
required. The line below would add a route for the <hostid
role="ipaddr">203.14.101.0</hostid> class C via the client's
ppp link.</para>
@ -878,7 +878,7 @@ exec /usr/sbin/ppp -direct pap$IDENT</programlisting>
<para>For each dialup line enabled in
<filename>/etc/ttys</filename> create a corresponding entry
in <filename>/etc/ppp/ppp.conf</filename>. This will
in <filename>/etc/ppp/ppp.conf</filename>. This will
happily co-exist with the definitions we created
above.</para>
@ -901,7 +901,7 @@ enable passwdauth</programlisting>
<para>If you wish to assign some users a static IP number, you can
specify the number as the third argument in
<filename>/etc/ppp/ppp.secret</filename>. See
<filename>/etc/ppp/ppp.secret</filename>. See
<filename>/etc/ppp/ppp.secret.sample</filename> for
examples.</para>
</sect5>
@ -943,7 +943,7 @@ set nbns 203.14.100.5</programlisting>
<para>Some ISPs set their system up so that the authentication
part of your connection is done using either of the PAP or CHAP
authentication mechanisms. If this is the case, your ISP will
authentication mechanisms. If this is the case, your ISP will
not give a <prompt>login:</prompt> prompt when you
connect, but will start talking PPP immediately.</para>
@ -964,7 +964,7 @@ set nbns 203.14.100.5</programlisting>
13 set authkey <replaceable>MyPassword</replaceable></programlisting>
<para>As always, do not include the line numbers, they are just
for reference in this discussion. Indentation of at least one
for reference in this discussion. Indentation of at least one
space is required.</para>
@ -972,7 +972,7 @@ set nbns 203.14.100.5</programlisting>
<varlistentry><term>Line 7:</term>
<listitem>
<para>Your ISP will not normally require that you log into
the server if you're using PAP or CHAP. You must
the server if you're using PAP or CHAP. You must
therefore disable your "set login" string.</para>
</listitem>
</varlistentry>
@ -980,7 +980,7 @@ set nbns 203.14.100.5</programlisting>
<varlistentry><term>Line 12:</term>
<listitem>
<para>This line specifies your PAP/CHAP user name. You
<para>This line specifies your PAP/CHAP user name. You
will need to insert the correct value for <replaceable>MyUserName</replaceable>.</para>
</listitem>
@ -989,8 +989,8 @@ set nbns 203.14.100.5</programlisting>
<varlistentry><term>Line 13:</term>
<listitem>
<para>This line specifies your PAP/CHAP password. You
will need to insert the correct value for <replaceable>MyPassword</replaceable>. You may want to add an
<para>This line specifies your PAP/CHAP password. You
will need to insert the correct value for <replaceable>MyPassword</replaceable>. You may want to add an
additional line
<programlisting>
@ -1011,7 +1011,7 @@ set nbns 203.14.100.5</programlisting>
<para>It is possible to talk to the <command>ppp</command> program while it is
running in the background, but only if a suitable diagnostic port has
been set up. To do this, add the following line to your
been set up. To do this, add the following line to your
configuration:</para>
<programlisting>
@ -1019,7 +1019,7 @@ set server /var/run/ppp-tun%d DiagnosticPassword 0177</programlisting>
<para>This will tell PPP to listen to the specified unix-domain
socket, asking clients for the specified password before allowing
access. The <literal>%d</literal> in the name is replaced with teh
access. The <literal>%d</literal> in the name is replaced with teh
tun device number that is in use.</para>
<para>Once a socket has been set up, the
@ -1033,7 +1033,7 @@ set server /var/run/ppp-tun%d DiagnosticPassword 0177</programlisting>
<title>Final system configuration</title>
<para>You now have <command>ppp</command> configured, but there are a few more things
to do before it is ready to work. They all involve editing the
to do before it is ready to work. They all involve editing the
<filename>/etc/rc.conf</filename> file (was
<filename>/etc/sysconfig</filename>).</para>
@ -1047,7 +1047,7 @@ hostname=foo.bar.com</programlisting>
name, it's probably best that you use this name as your host
name.</para>
<para>Look for the <literal>network_interfaces</literal> variable. If you want to
<para>Look for the <literal>network_interfaces</literal> variable. If you want to
configure your system to dial your ISP on demand, make sure the
<devicename>tun0</devicename> device is added to the list, otherwise remove it.</para>
@ -1057,15 +1057,15 @@ network_interfaces="lo0 tun0" ifconfig_tun0=</programlisting>
<note>
<para>The <literal>ifconfig_tun0</literal> variable should be empty,
and a file called <filename>/etc/start_if.tun0</filename> should
be created. This file should contain the line</para>
be created. This file should contain the line</para>
<programlisting>
ppp -auto mysystem</programlisting>
<para>This script is executed at network configuration time,
starting your ppp daemon in automatic mode. If you have a LAN
starting your ppp daemon in automatic mode. If you have a LAN
for which this machine is a gateway, you may also wish to use
the <option>-alias</option> switch. Refer to the manual page
the <option>-alias</option> switch. Refer to the manual page
for further details.</para>
</note>
@ -1082,7 +1082,7 @@ router=NO (/etc/sysconfig)</programlisting>
<para>It is probably worth your while ensuring that the
<literal>sendmail_flags</literal> line does not include the <option>-q</option> option,
otherwise <command>sendmail</command> will attempt to do a network lookup every now
and then, possibly causing your machine to dial out. You may
and then, possibly causing your machine to dial out. You may
try:</para>
<programlisting>
@ -1107,7 +1107,7 @@ sendmail_flags="-bd"</programlisting>
4 !bg sendmail -bd -q30m</programlisting>
<para>If you don't like this, it is possible to set up a &ldquo;dfilter&rdquo;
to block SMTP traffic. Refer to the sample files for further
to block SMTP traffic. Refer to the sample files for further
details.</para>
<para>All that is left is to reboot the machine.</para>
@ -1152,7 +1152,7 @@ sendmail_flags="-bd"</programlisting>
<step>
<para>Create an entry in
<filename>/etc/ppp/ppp.conf</filename>. The <filename>pmdemand</filename> example should suffice for
<filename>/etc/ppp/ppp.conf</filename>. The <filename>pmdemand</filename> example should suffice for
most ISPs.</para>
</step>
@ -1200,7 +1200,7 @@ sendmail_flags="-bd"</programlisting>
<step>
<para>Create an entry in
<filename>/etc/ppp/ppp.conf</filename>. The <filename>direct-server</filename> example should
<filename>/etc/ppp/ppp.conf</filename>. The <filename>direct-server</filename> example should
suffice.</para>
</step>
@ -1320,7 +1320,7 @@ defaultroute # put this if you want that PPP server will be your
</procedure>
<para>Now your computer is connected with PPP. If the connection
<para>Now your computer is connected with PPP. If the connection
fails for some reasons you can add the <option>debug</option> option to the
<filename>/etc/ppp/options</filename> file and check messages on
the console to track the problem</para>
@ -1351,7 +1351,7 @@ pppd /dev/tty01 19200</programlisting>
<para><filename>/etc/ppp/kermit.dial</filename> is kermit script
that dials and makes all necessary authorization on the remote
host. (Example of such script is attached to the end of this
host. (Example of such script is attached to the end of this
document)</para>
<para>Use the following <filename>/etc/ppp/pppdown</filename> script
@ -1564,8 +1564,8 @@ echo \13
exit</programlisting>
<para>This <filename>/etc/ppp/kermit.dial</filename> script is used
for dialing and authorizing on remote host. You will need to
customize it for your needs. Put your login and password in this
for dialing and authorizing on remote host. You will need to
customize it for your needs. Put your login and password in this
script, also you will need to change input statement depending on
responses from your modem and remote host.</para>
@ -1695,14 +1695,14 @@ exit 1
1995.</emphasis></para>
<para>The following is one way to set up a FreeBSD machine for SLIP on
a static host network. For dynamic hostname assignments (i.e., your
a static host network. For dynamic hostname assignments (i.e., your
address changes each time you dial up), you probably need to do
something much fancier.</para>
<para>First, determine which serial port your modem is connected to. I
<para>First, determine which serial port your modem is connected to. I
have a symbolic link to <filename>/dev/modem</filename> from
<filename>/dev/cuaa1</filename>, and only use the modem name in my configuration
files. It can become quite cumbersome when you need to fix a bunch
files. It can become quite cumbersome when you need to fix a bunch
of files in <filename>/etc</filename> and
<filename>.kermrc</filename>'s all over the system!</para>
@ -1714,7 +1714,7 @@ exit 1
<para>Make sure you have
<programlisting>
pseudo-device sl 1</programlisting> in your kernel's config file. It is included in
pseudo-device sl 1</programlisting> in your kernel's config file. It is included in
the <filename>GENERIC</filename> kernel, so this will not be a
problem unless you deleted it.</para>
@ -1727,7 +1727,7 @@ pseudo-device sl 1</programlisting> in your kernel's config file. It is i
<step>
<para>Add your home machine, the gateway and nameservers to
your <filename>/etc/hosts</filename> file. Mine looks like
your <filename>/etc/hosts</filename> file. Mine looks like
this:</para>
<programlisting>
@ -1744,12 +1744,12 @@ pseudo-device sl 1</programlisting> in your kernel's config file. It is i
<step>
<para>Make sure you have <option>hosts</option> before <option>bind</option> in your
<filename>/etc/host.conf</filename>. Otherwise, funny things
<filename>/etc/host.conf</filename>. Otherwise, funny things
may happen.</para>
</step>
<step>
<para>Edit the file <filename>/etc/rc.conf</filename>. Note
<para>Edit the file <filename>/etc/rc.conf</filename>. Note
that you should edit the file
<filename>/etc/sysconfig</filename> instead if you are
running FreeBSD previous to version 2.2.2.</para>
@ -1805,14 +1805,14 @@ domain HIP.Berkeley.EDU
nameserver 128.32.136.9
nameserver 128.32.136.12</programlisting>
<para>As you can see, these set up the nameserver hosts. Of
<para>As you can see, these set up the nameserver hosts. Of
course, the actual domain names and addresses depend on your
environment.</para>
</step>
<step>
<para>Set the password for root and toor (and any other
accounts that does not have a password). Use passwd, do not
accounts that does not have a password). Use passwd, do not
edit the <filename>/etc/passwd</filename> or
<filename>/etc/master.passwd</filename> files!</para>
</step>
@ -1835,8 +1835,8 @@ nameserver 128.32.136.12</programlisting>
<step>
<para>Dial up, type <command>slip</command> at the prompt, enter your machine
name and password. The things you need to enter depends on
your environment. I use kermit, with a script like this:</para>
name and password. The things you need to enter depends on
your environment. I use kermit, with a script like this:</para>
<programlisting>
# kermit setup
@ -1854,13 +1854,13 @@ output silvia\x0d, input 10 Password:, if failure stop, -
output ***\x0d, echo \x0aCONNECTED\x0a</programlisting>
<para>(of
course, you have to change the hostname and password to fit
yours). Then you can just type <command>slip</command> from the kermit
yours). Then you can just type <command>slip</command> from the kermit
prompt to get connected.</para>
<note>
<para>Leaving your password in plain text anywhere in the
filesystem is generally a BAD idea. Do it at your own
risk. I am just too lazy.</para>
filesystem is generally a BAD idea. Do it at your own
risk. I am just too lazy.</para>
</note>
</step>
@ -1891,16 +1891,16 @@ output ***\x0d, echo \x0aCONNECTED\x0a</programlisting>
<screen>&prompt.root; <userinput>kill -INT `cat /var/run/slattach.modem.pid`</userinput></screen>
(as root)
to kill slattach. Then go back to kermit (<command>fg</command> if you suspended
to kill slattach. Then go back to kermit (<command>fg</command> if you suspended
it) and exit from it (<command>q</command>).</para>
<para>The slattach man page says you have to use <command>ifconfig sl0 down</command>
to mark the interface down, but this does not seem to make any
difference for me. (<command>ifconfig sl0</command> reports the same
difference for me. (<command>ifconfig sl0</command> reports the same
thing.)</para>
<para>Some times, your modem might refuse to drop the carrier (mine
often does). In that case, simply start kermit and quit it again.
often does). In that case, simply start kermit and quit it again.
It usually goes out on the second try.</para>
</sect2>
@ -1908,7 +1908,7 @@ output ***\x0d, echo \x0aCONNECTED\x0a</programlisting>
<sect2>
<title>Troubleshooting</title>
<para>If it does not work, feel free to ask me. The things that
<para>If it does not work, feel free to ask me. The things that
people tripped over so far:</para>
<itemizedlist>
@ -1926,7 +1926,7 @@ output ***\x0d, echo \x0aCONNECTED\x0a</programlisting>
<listitem>
<para>Try <command>ifconfig sl0</command> to see your
interface status. I get:</para>
interface status. I get:</para>
<screen>&prompt.root; <userinput>ifconfig sl0</userinput>
@ -1938,7 +1938,7 @@ sl0: flags=10&lt;POINTOPOINT&gt;
<listitem>
<para>Also, <command>netstat -r</command> will give the
routing table, in case you get the "no route to host"
messages from ping. Mine looks like:</para>
messages from ping. Mine looks like:</para>
<screen>&prompt.root; <userinput>netstat -r</userinput>
@ -1974,17 +1974,17 @@ silvia.HIP.Berke localhost.Berkeley UGH 34 47641234 lo0 - 0.438
<para>This document provides suggestions for setting up SLIP Server
services on a FreeBSD system, which typically means configuring your
system to automatically startup connections upon login for remote
SLIP clients. The author has written this document based on his
SLIP clients. The author has written this document based on his
experience; however, as your system and needs may be different, this
document may not answer all of your questions, and the author cannot
be responsible if you damage your system or lose data due to
attempting to follow the suggestions here.</para>
<para>This guide was originally written for SLIP Server services on a
FreeBSD 1.x system. It has been modified to reflect changes in the
FreeBSD 1.x system. It has been modified to reflect changes in the
pathnames and the removal of the SLIP interface compression flags in
early versions of FreeBSD 2.X, which appear to be the only major
changes between FreeBSD versions. If you do encounter mistakes in
changes between FreeBSD versions. If you do encounter mistakes in
this document, please email the author with enough information to
help correct the problem.</para>
@ -1993,10 +1993,10 @@ silvia.HIP.Berke localhost.Berkeley UGH 34 47641234 lo0 - 0.438
<title>Prerequisites</title>
<para>This document is very technical in nature, so background
knowledge is required. It is assumed that you are familiar with
knowledge is required. It is assumed that you are familiar with
the TCP/IP network protocol, and in particular, network and node
addressing, network address masks, subnetting, routing, and
routing protocols, such as RIP. Configuring SLIP services on a
routing protocols, such as RIP. Configuring SLIP services on a
dial-up server requires a knowledge of these concepts, and if you
are not familiar with them, please read a copy of either Craig
Hunt's <emphasis>TCP/IP Network Administration</emphasis>
@ -2006,14 +2006,14 @@ silvia.HIP.Berke localhost.Berkeley UGH 34 47641234 lo0 - 0.438
<para>It is further assumed that you have already setup your
modem(s) and configured the appropriate system files to allow
logins through your modems. If you have not prepared your system
logins through your modems. If you have not prepared your system
for this yet, please see the tutorial for configuring dialup
services; if you have a World-Wide Web browser available, browse
the list of tutorials at <ulink
url="http://www.freebsd.org/">http://www.freebsd.org/</ulink>;
otherwise, check the place where you found this document for a
document named <filename>dialup.txt</filename> or something
similar. You may also want to check the manual pages for
similar. You may also want to check the manual pages for
<citerefentry><refentrytitle>sio</refentrytitle><manvolnum>4</manvolnum></citerefentry> for information on the serial
port device driver and <citerefentry><refentrytitle>ttys</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gettytab</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
@ -2032,7 +2032,7 @@ silvia.HIP.Berke localhost.Berkeley UGH 34 47641234 lo0 - 0.438
works as follows: a SLIP user dials up your FreeBSD SLIP Server
system and logs in with a special SLIP login ID that uses
<filename>/usr/sbin/sliplogin</filename> as the special user's
shell. The <command>sliplogin</command> program
shell. The <command>sliplogin</command> program
browses the file <filename>/etc/sliphome/slip.hosts</filename> to
find a matching line for the special user, and if it finds a
match, connects the serial line to an available SLIP interface and
@ -2078,7 +2078,7 @@ Shelmerg dc-slip sl-helmer 0xfffffc00 autocomp</programlisting>
to set the local IP address (<hostid>dc-slip</hostid>), remote
IP address (<hostid>sl-helmer</hostid>), network mask for the SLIP
interface (<hostid role="netmask">0xfffffc00</hostid>), and any additional
flags (<literal>autocomp</literal>). If something
flags (<literal>autocomp</literal>). If something
goes wrong, <command>sliplogin</command> usually logs
good informational messages via the <literal>daemon</literal> syslog facility,
which usually goes into <filename>/var/log/messages</filename>
@ -2115,7 +2115,7 @@ sl1* 296 &lt;Link&gt; 0 0 0 0
<para>The <devicename>sl0</devicename> and <devicename>sl1</devicename> interfaces shown in <command>netstat -i</command>'s output indicate that there are
two SLIP interfaces built into the kernel. (The asterisks after
two SLIP interfaces built into the kernel. (The asterisks after
the <literal>sl0</literal> and <literal>sl1</literal> indicate that the interfaces are
&ldquo;down&rdquo;.)</para>
@ -2207,7 +2207,7 @@ pseudo-device sl 2</programlisting>
domain name service, depending on your specifications in
<filename>/etc/host.conf</filename>), and I believe the network
mask may be a name that can be resolved by a lookup into
<filename>/etc/networks</filename>. On a sample system,
<filename>/etc/networks</filename>. On a sample system,
<filename>/etc/sliphome/slip.hosts</filename> looks like
this:</para>
@ -2260,7 +2260,7 @@ Shelmerg dc-slip sl-helmerg 0xfffffc00 autocomp</programlisting
links depends on whether you are going to dedicate a TCP/IP
subnet or if you are going to use &ldquo;proxy ARP&rdquo; on your SLIP
server (it is not &ldquo;true&rdquo; proxy ARP, but that is the
terminology used in this document to describe it). If you are
terminology used in this document to describe it). If you are
not sure which method to select or how to assign IP addresses,
please refer to the TCP/IP books referenced in the <link
linkend="slips-prereqs">slips-prereqs</link> section
@ -2269,7 +2269,7 @@ Shelmerg dc-slip sl-helmerg 0xfffffc00 autocomp</programlisting
<para>If you are going to use a separate subnet for your SLIP
clients, you will need to allocate the subnet number out of your
assigned IP network number and assign each of your SLIP client's
IP numbers out of that subnet. Then, you will probably either
IP numbers out of that subnet. Then, you will probably either
need to configure a static route to the SLIP subnet via your
SLIP server on your nearest IP router, or install <command>gated</command> on your FreeBSD SLIP server and
configure it to talk the appropriate routing protocols to your
@ -2331,7 +2331,7 @@ Shelmerg dc-slip sl-helmerg 0xfffffc00 autocomp</programlisting
<para>The additional line in this <filename>slip.login</filename>,
<command>arp -s &#36;5 00:11:22:33:44:55 pub</command>, creates
an ARP entry in the SLIP server's ARP table. This ARP entry
an ARP entry in the SLIP server's ARP table. This ARP entry
causes the SLIP server to respond with the SLIP server's
Ethernet MAC address whenever a another IP node on the Ethernet
asks to speak to the SLIP client's IP address.</para>
@ -2441,7 +2441,7 @@ Shelmerg dc-slip sl-helmerg 0xfffffc00 autocomp</programlisting
<para>Adding static routes to your nearest default routers can be
troublesome (or impossible, if you do not have authority to do
so...). If you have a multiple-router network in your
so...). If you have a multiple-router network in your
organization, some routers, such as Cisco and Proteon, may not
only need to be configured with the static route to the SLIP
subnet, but also need to be told which static routes to tell
@ -2461,7 +2461,7 @@ Shelmerg dc-slip sl-helmerg 0xfffffc00 autocomp</programlisting
You can use <command>gated</command> from the
<link linkend="ports">ports collection</link> or retrieve and
build it yourself from <ulink
URL="ftp://ftp.gated.merit.edu/research.and.development/gated/">the GateD anonymous ftp site</ulink>; I believe the current version as of this writing is <filename>gated-R3_5Alpha_8.tar.Z</filename>, which includes support for FreeBSD &ldquo;out-of-the-box&rdquo;. Complete information and documentation on <command>gated</command> is available on the Web starting at <ulink URL="http://www.gated.merit.edu/">the Merit GateD Consortium</ulink>. Compile and install it, and then write a <filename>/etc/gated.conf</filename> file to configure your gated; here is a sample, similar to what the author used on a FreeBSD SLIP server:</para>
URL="ftp://ftp.gated.merit.edu/research.and.development/gated/">the GateD anonymous ftp site</ulink>; I believe the current version as of this writing is <filename>gated-R3_5Alpha_8.tar.Z</filename>, which includes support for FreeBSD &ldquo;out-of-the-box&rdquo;. Complete information and documentation on <command>gated</command> is available on the Web starting at <ulink URL="http://www.gated.merit.edu/">the Merit GateD Consortium</ulink>. Compile and install it, and then write a <filename>/etc/gated.conf</filename> file to configure your gated; here is a sample, similar to what the author used on a FreeBSD SLIP server:</para>
<programlisting>
#
@ -2508,10 +2508,10 @@ import proto rip interface ed {
Ethernet; if you are using a different Ethernet driver than the
<devicename>ed</devicename> driver, you will need to change
the references to the <devicename>ed</devicename> interface
appropriately. This sample file also sets up tracing to
appropriately. This sample file also sets up tracing to
<filename>/var/tmp/gated.output</filename> for debugging
<command>gated</command>'s activity; you can
certainly turn off the tracing options if <command>gated</command> works OK for you. You will need to
certainly turn off the tracing options if <command>gated</command> works OK for you. You will need to
change the <replaceable>xxx.xxx.yy</replaceable>'s into the
network address of your own SLIP subnet (be sure to change the
net mask in the <literal>proto direct</literal>
@ -2522,7 +2522,7 @@ import proto rip interface ed {
to run <command>gated</command> in place of <command>routed</command> on your FreeBSD system; change the
<filename>routed/gated</filename> startup parameters in
<filename>/etc/netstart</filename> as appropriate for your
system. Please see the manual page for <command>gated</command> for information on <command>gated</command>'s command-line parameters.</para>
system. Please see the manual page for <command>gated</command> for information on <command>gated</command>'s command-line parameters.</para>
</sect3>
</sect2>

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

File diff suppressed because it is too large Load diff

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

@ -9,7 +9,7 @@
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
allocate. This will prevent one user from consuming all of the
available disk space.</para>
@ -17,7 +17,7 @@
<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
sure that quotas are configured in your kernel. This is done by
adding the following line to your kernel configuration file:</para>
<programlisting>
@ -26,12 +26,12 @@ 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
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
<filename>/etc/sysconfig</filename>. This is done by changing the
line:
<programlisting>
@ -50,19 +50,19 @@ quotas=YES</programlisting></para>
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
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>
to to enable quotas on. For example:</para>
<programlisting>
/dev/sd1s2g /home ufs rw,userquota 1 2</programlisting>
<para>Similarly, to enable group quotas, use the
<literal>groupquota</literal> option instead of the <literal>userquota</literal> keyword. To enable both user and
<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>
@ -71,20 +71,20 @@ check_quotas=YES</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
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
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
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>
@ -94,7 +94,7 @@ check_quotas=YES</programlisting>
<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>
that they really are enabled. An easy way to do this is to run</para>
<screen>&prompt.root; <userinput>quota -v</userinput></screen>
@ -109,28 +109,28 @@ check_quotas=YES</programlisting>
<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
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
<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
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
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
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
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
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>
@ -166,10 +166,10 @@ Quotas for user test:
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
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
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>
@ -179,7 +179,7 @@ Quotas for user test:
<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
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
@ -192,10 +192,10 @@ Quotas for user test:
<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>
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
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>
@ -213,12 +213,12 @@ Disk quotas for user test (uid 1002):
<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
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
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>

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

@ -10,14 +10,14 @@
<para>In order to protect the security of passwords on UN*X systems
from being easily exposed, passwords have traditionally been
scrambled in some way. Starting with Bell Labs' Seventh Edition
scrambled in some way. Starting with Bell Labs' Seventh Edition
Unix, passwords were encrypted using what the security people call a
&ldquo;one-way hash function&rdquo;. That is to say, the password is
&ldquo;one-way hash function&rdquo;. That is to say, the password is
transformed in such a way that the original password cannot be
regained except by brute-force searching the space of possible
passwords. Unfortunately, the only secure method that was available
passwords. Unfortunately, the only secure method that was available
to the AT&amp;T researchers at the time was based on DES, the Data
Encryption Standard. This causes only minimal difficulty for
Encryption Standard. This causes only minimal difficulty for
commercial vendors, but is a serious problem for an operating system
like FreeBSD where all the source code is freely available, because
national governments in many places like to place restrictions on
@ -28,23 +28,23 @@
still not running afoul of the law? We decided to take a dual-track
approach: we would make distributions which contained only a
non-regulated password scrambler, and then provide as a separate
add-on library the DES-based password hash. The password-scrambling
add-on library the DES-based password hash. The password-scrambling
function was moved out of the C library to a separate library,
called <filename>libcrypt</filename> because the name of
the C function to implement it is <function>crypt</function>. In FreeBSD 1.x and some pre-release
the C function to implement it is <function>crypt</function>. In FreeBSD 1.x and some pre-release
2.0 snapshots, the non-regulated scrambler uses an insecure function
written by Nate Williams; in subsequent releases this was replaced
by a mechanism using the RSA Data Security, Inc., MD5 one-way hash
function. Because neither of these functions involve encryption,
function. Because neither of these functions involve encryption,
they are believed to be exportable from the US and importable into
many other countries.</para>
<para>Meanwhile, work was also underway on the DES-based password hash
function. First, a version of the <function>crypt</function> function which was written outside the
US was imported, thus synchronizing the US and non-US code. Then,
function. First, a version of the <function>crypt</function> function which was written outside the
US was imported, thus synchronizing the US and non-US code. Then,
the library was modified and split into two; the DES <filename>libcrypt</filename> contains only the code involved in
performing the one-way password hash, and a separate <filename>libcipher</filename> was created with the entry points
to actually perform encryption. The code was partitioned in this
to actually perform encryption. The code was partitioned in this
way to make it easier to get an export license for the compiled
library.</para>
@ -54,8 +54,8 @@
mechanism</title>
<para>It is fairly easy to recognize whether a particular password
string was created using the DES- or MD5-based hash function. MD5
password strings always begin with the characters <literal>&#36;1&#36;</literal>. DES password strings do not
string was created using the DES- or MD5-based hash function. MD5
password strings always begin with the characters <literal>&#36;1&#36;</literal>. DES password strings do not
have any particular identifying characteristics, but they are
shorter than MD5 passwords, and are coded in a 64-character
alphabet which does not include the <literal>&#36;</literal> character, so a relatively short
@ -63,10 +63,10 @@
password.</para>
<para>Determining which library is being used on your system is
fairly easy for most programs, except for those like <command>init</command> which are statically linked. (For
fairly easy for most programs, except for those like <command>init</command> which are statically linked. (For
those programs, the only way is to try them on a known password
and see if it works.) Programs which use <function>crypt</function> are linked against <filename>libcrypt</filename>, which for each type of library is
a symbolic link to the appropriate implementation. For example,
a symbolic link to the appropriate implementation. For example,
on a system using the DES versions:</para>
@ -94,69 +94,69 @@ lrwxr-xr-x 1 bin bin 15 Sep 5 12:50 libcrypt_p.a -&gt; libdescrypt_p.a</scre
<para>S/Key is a one-time password scheme based on a one-way hash
function (in our version, this is MD4 for compatibility; other
versions have used MD5 and DES-MAC). S/Key has been a standard part
versions have used MD5 and DES-MAC). S/Key has been a standard part
of all FreeBSD distributions since version 1.1.5, and is also
implemented on a large and growing number of other systems. S/Key
implemented on a large and growing number of other systems. S/Key
is a registered trademark of Bell Communications Research,
Inc.</para>
<para>There are three different sorts of passwords which we will talk
about in the discussion below. The first is your usual UNIX-style
or Kerberos password; we will call this a &ldquo;UNIX password&rdquo;. The
about in the discussion below. The first is your usual UNIX-style
or Kerberos password; we will call this a &ldquo;UNIX password&rdquo;. The
second sort is the one-time password which is generated by the S/Key
<command>key</command> program and accepted by the
<command>keyinit</command> program and the login
prompt; we will call this a &ldquo;one-time password&rdquo;. The final sort
prompt; we will call this a &ldquo;one-time password&rdquo;. The final sort
of password is the secret password which you give to the <command>key</command> program (and sometimes the <command>keyinit</command> program) which it uses to generate
one-time passwords; we will call it a &ldquo;secret password&rdquo; or just
unqualified &ldquo;password&rdquo;.</para>
<para>The secret password does not necessarily have anything to do
with your UNIX password (while they can be the same, this is not
recommended). While UNIX passwords are limited to eight characters
recommended). While UNIX passwords are limited to eight characters
in length, your S/Key secret password can be as long as you like; I
use seven-word phrases. In general, the S/Key system operates
use seven-word phrases. In general, the S/Key system operates
completely independently of the UNIX password system.</para>
<para>There are in addition two other sorts of data involved in the
S/Key system; one is called the &ldquo;seed&rdquo; or (confusingly) &ldquo;key&rdquo;,
and consists of two letters and five digits, and the other is the
&ldquo;iteration count&rdquo; and is a number between 100 and 1. S/Key
&ldquo;iteration count&rdquo; and is a number between 100 and 1. S/Key
constructs a one-time password from these components by
concatenating the seed and the secret password, then applying a
one-way hash (the RSA Data Security, Inc., MD4 secure hash function)
iteration-count times, and turning the result into six short English
words. The <command>login</command> and <command>su</command> programs keep track of the last one-time
words. The <command>login</command> and <command>su</command> programs keep track of the last one-time
password used, and the user is authenticated if the hash of the
user-provided password is equal to the previous password. Because a
user-provided password is equal to the previous password. Because a
one-way hash function is used, it is not possible to generate future
one-time passwords having overheard one which was successfully used;
the iteration count is decremented after each successful login to
keep the user and login program in sync. (When you get the
keep the user and login program in sync. (When you get the
iteration count down to 1, it is time to reinitialize S/Key.)</para>
<para>There are four programs involved in the S/Key system which we
will discuss below. The <command>key</command> program
will discuss below. The <command>key</command> program
accepts an iteration count, a seed, and a secret password, and
generates a one-time password. The <command>keyinit</command> program is used to initialized S/Key,
generates a one-time password. The <command>keyinit</command> program is used to initialized S/Key,
and to change passwords, iteration counts, or seeds; it takes either
a secret password, or an iteration count, seed, and one-time
password. The <command>keyinfo</command> program
password. The <command>keyinfo</command> program
examines the <filename>/etc/skeykeys</filename> file and prints out
the invoking user's current iteration count and seed. Finally, the
the invoking user's current iteration count and seed. Finally, the
<command>login</command> and <command>su</command> programs contain the necessary logic to
accept S/Key one-time passwords for authentication. The <command>login</command> program is also capable of disallowing
accept S/Key one-time passwords for authentication. The <command>login</command> program is also capable of disallowing
the use of UNIX passwords on connections coming from specified
addresses.</para>
<para>There are four different sorts of operations we will cover. The
<para>There are four different sorts of operations we will cover. The
first is using the <command>keyinit</command> program
over a secure connection to set up S/Key for the first time, or to
change your password or seed. The second operation is using the
change your password or seed. The second operation is using the
<command>keyinit</command> program over an insecure
connection, in conjunction with the <command>key</command> program over a secure connection, to do
the same. The third is using the <command>key</command> program to log in over an insecure
connection. The fourth is using the <command>key</command> program to generate a number of keys
the same. The third is using the <command>key</command> program to log in over an insecure
connection. The fourth is using the <command>key</command> program to generate a number of keys
which can be written down or printed out to carry with you when
going to some location without secure connections to anywhere (like
at a conference).</para>
@ -185,14 +185,14 @@ HAS FONT GOUT FATE BOOM )</screen>
<para>There is a lot of information here. At the<prompt>Enter secret
<para>There is a lot of information here. At the<prompt>Enter secret
password:</prompt> prompt, you should enter some password or phrase (I use
phrases of minimum seven words) which will be needed to generate
login keys. The line starting `ID' gives the parameters of your
login keys. The line starting `ID' gives the parameters of your
particular S/Key instance: your login name, the iteration count,
and seed. When logging in with S/Key, the system will remember
and seed. When logging in with S/Key, the system will remember
these parameters and present them back to you so you do not have
to remember them. The last line gives the particular one-time
to remember them. The last line gives the particular one-time
password which corresponds to those parameters and your secret
password; if you were to re-login immediately, this one-time
password is the one you would use.</para>
@ -206,9 +206,9 @@ HAS FONT GOUT FATE BOOM )</screen>
insecure connection, you will need to already have a secure
connection to some place where you can run the <command>key</command> program; this might be in the form of a
desk accessory on a Macintosh, or a shell prompt on a machine you
trust (we will show the latter). You will also need to make up an
trust (we will show the latter). You will also need to make up an
iteration count (100 is probably a good value), and you may make
up your own seed or use a randomly-generated one. Over on the
up your own seed or use a randomly-generated one. Over on the
insecure connection (to the machine you are initializing), use the
<command>keyinit -s</command> command:</para>
@ -224,7 +224,7 @@ s/key 100 kh94742</screen>
<para>To accept the default seed (which the <command>keyinit</command> program
confusingly calls a <literal>key</literal>), press return. Then move over to your
confusingly calls a <literal>key</literal>), press return. Then move over to your
secure connection or S/Key desk accessory, and give it the same
parameters:</para>
@ -274,10 +274,10 @@ s/key 92 hi52030
<para>Note that, before prompting for a password, the login program
prints out the iteration number and seed which you will need in
order to generate the appropriate key. You will also find a
order to generate the appropriate key. You will also find a
useful feature (not shown here): if you press return at the
password prompt, the login program will turn echo on, so you can
see what you are typing. This can be extremely useful if you are
see what you are typing. This can be extremely useful if you are
attempting to type in an S/Key by hand, such as from a
printout.</para>
@ -293,13 +293,13 @@ s/key 92 hi52030
<title>Generating a single one-time password</title>
<para>Now, to generate the one-time password needed to answer this
login prompt, we use a trusted machine and the <command>key</command> program. (There are versions of the
login prompt, we use a trusted machine and the <command>key</command> program. (There are versions of the
<command>key</command> program from DOS and Windows
machines, and there is an S/Key desk accessory for Macintosh
computers as well.) The command-line <command>key</command> program takes as its parameters the
iteration count and seed; you can cut-and-paste right from the
login prompt starting at <literal>key</literal> to
the end of the line. Thus:</para>
the end of the line. Thus:</para>
@ -324,7 +324,7 @@ Last login: Wed Jun 28 15:31:00 from halloran-eldar.l
<para>This is the easiest mechanism <emphasis>if</emphasis> you have
a trusted machine. There is a Java S/Key <command>key</command> applet, <ulink
a trusted machine. There is a Java S/Key <command>key</command> applet, <ulink
URL="http://www.cs.umd.edu/~harry/jotp/src.html">The Java OTP
Calculator</ulink>, that you can download and run locally on any
Java supporting brower.</para>
@ -335,10 +335,10 @@ Last login: Wed Jun 28 15:31:00 from halloran-eldar.l
<title>Generating multiple one-time passwords</title>
<para>Sometimes we have to go places where no trusted machines or
connections are available. In this case, it is possible to use
connections are available. In this case, it is possible to use
the <command>key</command> command to generate a
number of one-time passwords in the same command; these can then
be printed out. For example:</para>
be printed out. For example:</para>
@ -356,10 +356,10 @@ Reminder - Do not use this program while logged in via telnet or rlogin.
<para>The <option>-n 25</option> requests twenty-five keys in
sequence; the <option>57</option> indicates the
<emphasis>ending</emphasis> iteration number; and the rest is as
before. Note that these are printed out in
<emphasis>reverse</emphasis> order of eventual use. If you are
before. Note that these are printed out in
<emphasis>reverse</emphasis> order of eventual use. If you are
really paranoid, you might want to write the results down by hand;
otherwise you can cut-and-paste into <command>lpr</command>. Note that each line shows both the
otherwise you can cut-and-paste into <command>lpr</command>. Note that each line shows both the
iteration count and the one-time password; you may still find it
handy to scratch off passwords as you use them.</para>
@ -371,17 +371,17 @@ Reminder - Do not use this program while logged in via telnet or rlogin.
<para>The configuration file <filename>/etc/skey.access</filename>
can be used to configure restrictions on the use of UNIX passwords
based on the host name, user name, terminal port, or IP address of
a login session. The complete format of the file is documented in
a login session. The complete format of the file is documented in
the <citerefentry><refentrytitle>skey.access</refentrytitle><manvolnum>5</manvolnum></citerefentry> manual page; there are
also some security cautions there which should be read before
depending on this file for security.</para>
<para>If there is no <filename>/etc/skey.access</filename> file
(which is the default state as FreeBSD is shipped), then all users
will be allowed to use UNIX passwords. If the file exists,
will be allowed to use UNIX passwords. If the file exists,
however, then all users will be required to use S/Key unless
explicitly permitted to do otherwise by configuration statements
in the <filename>skey.access</filename> file. In all cases, UNIX
in the <filename>skey.access</filename> file. In all cases, UNIX
passwords are permitted on the console.</para>
<para>Here is a sample configuration file which illustrates the
@ -395,7 +395,7 @@ permit port ttyd0</programlisting>
<para>The first line (<literal>permit
internet</literal>) allows users whose IP source address
(which is vulnerable to spoofing) matches the specified value and
mask, to use UNIX passwords. This should not be considered a
mask, to use UNIX passwords. This should not be considered a
security mechanism, but rather, a means to remind authorized users
that they are using an insecure network and need to use S/Key for
authentication.</para>
@ -427,7 +427,7 @@ permit port ttyd0</programlisting>
more controllable.</para>
<para>The following instructions can be used as a guide on how to set
up Kerberos as distributed for FreeBSD. However, you should refer to
up Kerberos as distributed for FreeBSD. However, you should refer to
the relevant manual pages for a complete description.</para>
<para>In FreeBSD, the Kerberos is not that from the original
@ -438,7 +438,7 @@ permit port ttyd0</programlisting>
<para>For those needing to get a legal foreign distribution of this
software, please <emphasis>do not</emphasis> get it from a USA or
Canada site. You will get that site in <emphasis>big</emphasis>
Canada site. You will get that site in <emphasis>big</emphasis>
trouble! A legal copy of this is available from
<hostid role="fqdn">ftp.internat.freebsd.org</hostid>, which is in
South Africa and an official FreeBSD mirror site.</para>
@ -447,8 +447,8 @@ permit port ttyd0</programlisting>
<sect2>
<title>Creating the initial database</title>
<para>This is done on the Kerberos server only. First make sure that
you do not have any old Kerberos databases around. You should
<para>This is done on the Kerberos server only. First make sure that
you do not have any old Kerberos databases around. You should
change to the directory <filename>/etc/kerberosIV</filename> and
check that only the following files are present:</para>
@ -468,9 +468,9 @@ README krb.conf krb.realms</screen>
<para>You should now edit the <filename>krb.conf</filename> and
<filename>krb.realms</filename> files to define your Kerberos
realm. In this case the realm will be
realm. In this case the realm will be
<filename>GRONDAR.ZA</filename> and the server is
<filename>grunt.grondar.za</filename>. We edit or create the
<filename>grunt.grondar.za</filename>. We edit or create the
<filename>krb.conf</filename> file:</para>
@ -487,23 +487,23 @@ TELECOM.MIT.EDU bitsy.mit.edu
ARC.NASA.GOV trident.arc.nasa.gov</screen>
<para>In this case, the other realms do not need to be there. They
<para>In this case, the other realms do not need to be there. They
are here as an example of how a machine may be made aware of
multiple realms. You may wish to not include them for
multiple realms. You may wish to not include them for
simplicity.</para>
<para>The first line names the realm in which this system works. The
other lines contain realm/host entries. The first item on a line
<para>The first line names the realm in which this system works. The
other lines contain realm/host entries. The first item on a line
is a realm, and the second is a host in that realm that is acting
as a &ldquo;key distribution centre&rdquo;. The words <literal>admin server</literal>
as a &ldquo;key distribution centre&rdquo;. The words <literal>admin server</literal>
following a hosts name means that host also provides an
administrative database server. For further explanation of these
administrative database server. For further explanation of these
terms, please consult the Kerberos man pages.</para>
<para>Now we have to add <hostid role="fqdn">grunt.grondar.za</hostid> to
the <filename>GRONDAR.ZA</filename> realm and also add an entry to
put all hosts in the <hostid role="domainname">.grondar.za</hostid> domain in
the <filename>GRONDAR.ZA</filename> realm. The
the <filename>GRONDAR.ZA</filename> realm. The
<filename>krb.realms</filename> file would be updated as
follows:</para>
@ -516,16 +516,16 @@ grunt.grondar.za GRONDAR.ZA
.mit.edu ATHENA.MIT.EDU</screen>
<para>Again, the other realms do not need to be there. They are here
<para>Again, the other realms do not need to be there. They are here
as an example of how a machine may be made aware of multiple
realms. You may wish to remove them to simplify things.</para>
realms. You may wish to remove them to simplify things.</para>
<para>The first line puts the <emphasis>specific</emphasis>
system into the named realm. The rest of the lines show how to
system into the named realm. The rest of the lines show how to
default systems of a particular subdomain to a named realm.</para>
<para>Now we are ready to create the database. This only needs to
run on the Kerberos server (or Key Distribution Centre). Issue the
<para>Now we are ready to create the database. This only needs to
run on the Kerberos server (or Key Distribution Centre). Issue the
<command>kdb_init</command> command to do this:</para>
@ -538,7 +538,7 @@ It is important that you NOT FORGET this password.
<para>Now we have to save the key so that servers on the local
machine can pick it up. Use the <command>kstash</command> command to do this.</para>
machine can pick it up. Use the <command>kstash</command> command to do this.</para>
<screen>&prompt.root; <userinput>kstash</userinput>
@ -559,7 +559,7 @@ Master key entered. BEWARE!</screen>
<title>Making it all run</title>
<para>Two principals need to be added to the database for <emphasis>each</emphasis> system that will be secured with
Kerberos. Their names are <literal>kpasswd</literal>
Kerberos. Their names are <literal>kpasswd</literal>
and <literal>rcmd</literal> These two principals are
made for each system, with the instance being the name of the
individual system.</para>
@ -630,11 +630,11 @@ Edit O.K.
<title>Creating the server file</title>
<para>We now have to extract all the instances which define the
services on each machine. For this we use the
<command>ext_srvtab</command> command. This will create a file which
services on each machine. For this we use the
<command>ext_srvtab</command> command. This will create a file which
must be copied or moved <emphasis>by secure
means</emphasis> to each Kerberos client's /etc/kerberosIV
directory. This file must be present on each server and client,
directory. This file must be present on each server and client,
and is crucial to the operation of Kerberos.</para>
@ -649,7 +649,7 @@ Generating 'grunt-new-srvtab'....</screen>
<para>Now, this command only generates a temporary file which must
be renamed to <filename>srvtab</filename> so that all the
server can pick it up. Use the <command>mv</command>
server can pick it up. Use the <command>mv</command>
command to move it into place on the original system:</para>
@ -658,7 +658,7 @@ Generating 'grunt-new-srvtab'....</screen>
<para>If the file is for a client system, and the network is not
deemed safe, then copy the <filename><replaceable>client</replaceable>-new-srvtab</filename> to removable media
and transport it by secure physical means. Be sure to rename it to
and transport it by secure physical means. Be sure to rename it to
<filename>srvtab</filename> in the client's
<filename>/etc/kerberosIV</filename> directory, and make sure it
is mode 600:</para>
@ -672,8 +672,8 @@ Generating 'grunt-new-srvtab'....</screen>
<sect2>
<title>Populating the database</title>
<para>We now have to add some user entries into the database. First
let's create an entry for the user <username>jane</username>. Use
<para>We now have to add some user entries into the database. First
let's create an entry for the user <username>jane</username>. Use
the <command>kdb_edit</command> command to do this:</para>
@ -710,10 +710,10 @@ Edit O.K.
<sect2>
<title>Testing it all out</title>
<para>First we have to start the Kerberos daemons. NOTE that if you
<para>First we have to start the Kerberos daemons. NOTE that if you
have correctly edited your <filename>/etc/rc.conf</filename> then
this will happen automatically when you reboot. This is only
necessary on the Kerberos server. Kerberos clients will
this will happen automatically when you reboot. This is only
necessary on the Kerberos server. Kerberos clients will
automagically get what they need from the
<filename>/etc/kerberosIV</filename> directory.</para>
@ -777,10 +777,10 @@ Password changed.</screen>
<title>Adding <command>su</command> privileges</title>
<para>Kerberos allows us to give <emphasis>each</emphasis>
user who needs root privileges their own <emphasis>separate</emphasis> <command>su</command>password. We could now add an id which is
authorized to <command>su</command> to <username>root</username>. This is controlled by having an
user who needs root privileges their own <emphasis>separate</emphasis> <command>su</command>password. We could now add an id which is
authorized to <command>su</command> to <username>root</username>. This is controlled by having an
instance of <username>root</username> associated with a
principal. Using <command>kdb_edit</command> we can create the
principal. Using <command>kdb_edit</command> we can create the
entry <literal>jane.root</literal> in the Kerberos
database:</para>
@ -855,7 +855,7 @@ May 2 20:43:12 May 3 04:43:12 krbtgt.GRONDAR.ZA@GRONDAR.ZA</screen>
<title>Using other commands</title>
<para>In an earlier example, we created a principal called
<literal>jane</literal> with an instance <literal>root</literal>. This was based on a user with the same
<literal>jane</literal> with an instance <literal>root</literal>. This was based on a user with the same
name as the principal, and this is a Kerberos default; that a
<literal>&lt;principal&gt;.&lt;instance&gt;</literal> of the
form <literal>&lt;username&gt;.</literal><literal>root</literal> will allow that
@ -926,7 +926,7 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
<para>Firewalls are an area of increasing interest for people who are
connected to the Internet, and are even finding applications on
private networks to provide enhanced security. This section will
private networks to provide enhanced security. This section will
hopefully explain what firewalls are, how to use them, and how to
use the facilities provided in the FreeBSD kernel to implement
them.</para>
@ -937,10 +937,10 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
will solve all your security problems.</para>
<para>It may help, but a poorly setup firewall system is more of a
security risk than not having one at all. A firewall can only add
security risk than not having one at all. A firewall can only add
another layer of security to your systems, but they will not be
able to stop a really determined cracker from penetrating your
internal network. If you let internal security lapse because you
internal network. If you let internal security lapse because you
believe your firewall to be impenetrable, you have just made the
crackers job that bit easier.</para>
</note>
@ -950,10 +950,10 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
<title>What is a firewall?</title>
<para>There are currently two distinct types of firewalls in common
use on the Internet today. The first type is more properly called
use on the Internet today. The first type is more properly called
a <emphasis>packet filtering router</emphasis>, where the
kernel on a multi-homed machine chooses whether to forward or
block packets based on a set of rules. The second type, known as
block packets based on a set of rules. The second type, known as
<emphasis>proxy servers</emphasis>, rely on daemons to
provide authentication and to forward packets, possibly on a
multi-homed machine which has kernel packet forwarding
@ -962,13 +962,13 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
<para>Sometimes sites combine the two types of firewalls, so that
only a certain machine (known as a <emphasis>bastion
host</emphasis>) is allowed to send packets through a packet
filtering router onto an internal network. Proxy services are run
filtering router onto an internal network. Proxy services are run
on the bastion host, which are generally more secure than normal
authentication mechanisms.</para>
<para>FreeBSD comes with a kernel packet filter (known as
<application>IPFW</application>), which is what the rest of this section
will concentrate on. Proxy servers can be built on FreeBSD from
will concentrate on. Proxy servers can be built on FreeBSD from
third party software, but there is such a variety of proxy servers
available that it would be impossible to cover them in this
document.</para>
@ -978,22 +978,22 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
<title>Packet filtering routers</title>
<para>A router is a machine which forwards packets between two or
more networks. A packet filtering router has an extra piece of
more networks. A packet filtering router has an extra piece of
code in its kernel, which compares each packet to a list of
rules before deciding if it should be forwarded or not. Most
rules before deciding if it should be forwarded or not. Most
modern IP routing software has packet filtering code in it,
which defaults to forwarding all packets. To enable the filters,
which defaults to forwarding all packets. To enable the filters,
you need to define a set of rules for the filtering code, so
that it can decide if the packet should be allowed to pass or
not.</para>
<para>To decide if a packet should be passed on or not, the code
looks through its set of rules for a rule which matches the
contents of this packets headers. Once a match is found, the
rule action is obeyed. The rule action could be to drop the
contents of this packets headers. Once a match is found, the
rule action is obeyed. The rule action could be to drop the
packet, to forward the packet, or even to send an ICMP message
back to the originator. Only the first match counts, as the
rules are searched in order. Hence, the list of rules can be
back to the originator. Only the first match counts, as the
rules are searched in order. Hence, the list of rules can be
referred to as a &ldquo;rule chain&rdquo;.</para>
<para>The packet matching criteria varies depending on the
@ -1012,7 +1012,7 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
daemons (telnetd, ftpd, etc) replaced with special servers.
These servers are called <emphasis>proxy
servers</emphasis> as they normally only allow onward
connections to be made. This enables you to run (for example) a
connections to be made. This enables you to run (for example) a
proxy telnet server on your firewall host, and people can telnet
in to your firewall from the outside, go through some
authentication mechanism, and then gain access to the internal
@ -1024,14 +1024,14 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
available, including &ldquo;one-shot&rdquo; password systems so that even
if someone manages to discover what password you used, they will
not be able to use it to gain access to your systems as the
password instantly expires. As they do not actually give users
password instantly expires. As they do not actually give users
access to the host machine, it becomes a lot more difficult for
someone to install backdoors around your security system.</para>
<para>Proxy servers often have ways of restricting access further,
so that only certain hosts can gain access to the servers, and
often they can be set up so that you can limit which users can
talk to which destination machine. Again, what facilities are
talk to which destination machine. Again, what facilities are
available depends largely on what proxy software you
choose.</para>
@ -1044,14 +1044,14 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
<para><application>IPFW</application>, the software supplied with FreeBSD,
is a packet filtering and accounting system which resides in the
kernel, and has a user-land control utility,
<citerefentry><refentrytitle>ipfw</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Together, they allow you to define and
<citerefentry><refentrytitle>ipfw</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Together, they allow you to define and
query the rules currently used by the kernel in its routing
decisions.</para>
<para>There are two related parts to <application>IPFW</application>. The
firewall section allows you to perform packet filtering. There is
firewall section allows you to perform packet filtering. There is
also an IP accounting section which allows you to track usage of
your router, based on similar rules to the firewall section. This
your router, based on similar rules to the firewall section. This
allows you to see (for example) how much traffic your router is
getting from a certain machine, or how much WWW (World Wide Web)
traffic it is forwarding.</para>
@ -1059,7 +1059,7 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
<para>As a result of the way that <application>IPFW</application> is
designed, you can use <application>IPFW</application> on non-router
machines to perform packet filtering on incoming and outgoing
connections. This is a special case of the more general use of
connections. This is a special case of the more general use of
<application>IPFW</application>, and the same commands and techniques
should be used in this situation.</para>
@ -1071,7 +1071,7 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
<para>As the main part of the <application>IPFW</application> system lives
in the kernel, you will need to add one or more options to your
kernel configuration file, depending on what facilities you want,
and recompile your kernel. See
and recompile your kernel. See
<link linkend="kernelconfig">reconfiguring the kernel</link> for
more details on how to recompile your kernel.</para>
@ -1091,7 +1091,7 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
<listitem>
<para>Enables code to allow logging of packets through
<citerefentry><refentrytitle>syslogd</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Without this option, even
<citerefentry><refentrytitle>syslogd</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Without this option, even
if you specify that packets should be logged in the filter
rules, nothing will happen.</para>
</listitem>
@ -1101,14 +1101,14 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
<listitem>
<para>Limits the number of packets logged through
<citerefentry><refentrytitle>syslogd</refentrytitle><manvolnum>8</manvolnum></citerefentry> on a per entry basis. You
<citerefentry><refentrytitle>syslogd</refentrytitle><manvolnum>8</manvolnum></citerefentry> on a per entry basis. You
may wish to use this option in hostile environments in
which you want to log firewall activity, but do not want
to be open to a denial of service attack via syslog
flooding.</para>
<para>When a chain entry reaches the packet limit specified,
logging is turned off for that particular entry. To
logging is turned off for that particular entry. To
resume logging, you will need to reset the associated
counter using the <citerefentry><refentrytitle>ipfw</refentrytitle><manvolnum>8</manvolnum></citerefentry>
utility:</para>
@ -1125,7 +1125,7 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
<para>Previous versions of FreeBSD contained an
<literal>IPFIREWALL_ACCT</literal> option. This is now obsolete as
<literal>IPFIREWALL_ACCT</literal> option. This is now obsolete as
the firewall code automatically includes accounting
facilities.</para>
@ -1135,17 +1135,17 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
<title>Configuring IPFW</title>
<para>The configuration of the <application>IPFW</application> software is
done through the <citerefentry><refentrytitle>ipfw</refentrytitle><manvolnum>8</manvolnum></citerefentry> utility. The syntax
done through the <citerefentry><refentrytitle>ipfw</refentrytitle><manvolnum>8</manvolnum></citerefentry> utility. The syntax
for this command looks quite complicated, but it is relatively
simple once you understand its structure.</para>
<para>There are currently four different command categories used by
the utility: addition/deletion, listing, flushing, and clearing.
Addition/deletion is used to build the rules that control how
packets are accepted, rejected, and logged. Listing is used to
packets are accepted, rejected, and logged. Listing is used to
examine the contents of your rule set (otherwise known as the
chain) and packet counters (accounting). Flushing is used to
remove all entries from the chain. Clearing is used to zero out
chain) and packet counters (accounting). Flushing is used to
remove all entries from the chain. Clearing is used to zero out
one or more accounting entries.</para>
@ -1181,7 +1181,7 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
<para>The <emphasis>command</emphasis> given can be shortened to
the shortest unique form. The valid
the shortest unique form. The valid
<emphasis>commands</emphasis> are:</para>
@ -1204,7 +1204,7 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
<para>Previous versions of <application>IPFW</application> used separate
firewall and accounting entries. The present version provides
firewall and accounting entries. The present version provides
packet accounting with each firewall entry.</para>
<para>If an <emphasis>index</emphasis> value is supplied,
@ -1232,7 +1232,7 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
<varlistentry><term>allow</term>
<listitem>
<para>Pass the packet on as normal. (aliases:
<para>Pass the packet on as normal. (aliases:
<literal>pass</literal> and <literal>accept</literal>)</para>
</listitem>
</varlistentry>
@ -1240,7 +1240,7 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
<varlistentry><term>deny</term>
<listitem>
<para>Drop the packet. The source is not notified via an
<para>Drop the packet. The source is not notified via an
ICMP message (thus it appears that the packet never
arrived at the destination).</para>
</listitem>
@ -1250,7 +1250,7 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
<listitem>
<para>Update packet counters but do not allow/deny the
packet based on this rule. The search continues with
packet based on this rule. The search continues with
the next chain entry.</para>
</listitem>
</varlistentry>
@ -1310,9 +1310,9 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
<para>The <option>via</option> is optional and may
specify the IP address or domain name of a local IP interface,
or an interface name (e.g. <devicename>ed0</devicename>) to
match only packets coming through this interface. Interface unit
numbers can be specified with an optional wildcard. For example,
or an interface name (e.g. <devicename>ed0</devicename>) to
match only packets coming through this interface. Interface unit
numbers can be specified with an optional wildcard. For example,
<literal>ppp*</literal> would match all kernel PPP
interfaces.</para>
@ -1336,11 +1336,11 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
</para>
<para>A valid hostname may be specified in place of the IP
address. <option><replaceable>mask-bits</replaceable></option> is a decimal
address. <option><replaceable>mask-bits</replaceable></option> is a decimal
number representing how many bits in the address mask should be
set. e.g. specifying <literal>192.216.222.1/24</literal> will create a mask which will allow any
set. e.g. specifying <literal>192.216.222.1/24</literal> will create a mask which will allow any
address in a class C subnet (in this case, 192.216.222) to be
matched. <option><replaceable>mask-pattern</replaceable></option> is an IP
matched. <option><replaceable>mask-pattern</replaceable></option> is an IP
address which will be logically AND'ed with the address given.
The keyword <literal>any</literal> may be used to
specify &ldquo;any IP address&rdquo;.</para>
@ -1354,7 +1354,7 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
<cmdsynopsis>
<arg choice="plain"><replaceable>port</replaceable>-<replaceable>port</replaceable></arg>
</cmdsynopsis> to specify a range of ports. You may also
</cmdsynopsis> to specify a range of ports. You may also
combine a single range with a list, but the range must always be
specified first.</para>
@ -1388,12 +1388,12 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
<listitem>
<para>Matches if the IP header contains the comma
separated list of options specified in
<replaceable>spec</replaceable>. The supported list of IP
<replaceable>spec</replaceable>. The supported list of IP
options are: <literal>ssrr</literal> (strict
source route), <literal>lsrr</literal> (loose
source route), <literal>rr</literal> (record
packet route), and <literal>ts</literal>
(timestamp). The absence of a particular option may be
(timestamp). The absence of a particular option may be
denoted with a leading <literal>!</literal>.</para>
</listitem>
</varlistentry>
@ -1403,7 +1403,7 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
<listitem>
<para>Matches if the packet is part of an already
established TCP connection (i.e. it has the RST or ACK
bits set). You can optimize the performance of the
bits set). You can optimize the performance of the
firewall by placing <emphasis>established</emphasis>
rules early in the chain.</para>
</listitem>
@ -1422,11 +1422,11 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
<listitem>
<para>Matches if the TCP header contains the comma
separated list of <replaceable>flags</replaceable>. The
separated list of <replaceable>flags</replaceable>. The
supported flags are <literal>fin</literal>,
<literal>syn</literal>, <literal>rst</literal>,
<literal>psh</literal>, <literal>ack</literal>, and
<literal>urg</literal>. The absence of a particular
<literal>urg</literal>. The absence of a particular
flag may be indicated by a leading <literal>!</literal>.</para>
</listitem>
</varlistentry>
@ -1435,9 +1435,9 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
<listitem>
<para>Matches if the ICMP type is present in the list
<replaceable>types</replaceable>. The list may be specified
<replaceable>types</replaceable>. The list may be specified
as any combination of ranges and/or individual types
separated by commas. Commonly used ICMP types are:
separated by commas. Commonly used ICMP types are:
<literal>0</literal> echo reply (ping reply),
<literal>3</literal> destination unreachable,
<literal>5</literal> redirect, <literal>8</literal> echo request (ping request), and
@ -1470,7 +1470,7 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
<variablelist>
<varlistentry><term>-a</term>
<listitem>
<para>While listing, show counter values. This option is
<para>While listing, show counter values. This option is
the only way to see accounting counters.</para>
</listitem>
</varlistentry>
@ -1507,7 +1507,7 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
<para>This causes all entries in the firewall chain to be removed
except the fixed default policy enforced by the kernel (index
65535). Use caution when flushing rules, the default deny
65535). Use caution when flushing rules, the default deny
policy will leave your system cut off from the network until
allow entries are added to the chain.</para>
@ -1524,7 +1524,7 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
</cmdsynopsis></para>
<para>When used without an <replaceable>index</replaceable> argument,
all packet counters are cleared. If an
all packet counters are cleared. If an
<replaceable>index</replaceable> is supplied, the clearing operation
only affects a specific chain entry.</para>
@ -1582,7 +1582,7 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
<title>Building a packet filtering firewall</title>
<note>
<para>The following suggestions are just that: suggestions. The
<para>The following suggestions are just that: suggestions. The
requirements of each firewall are different and I cannot tell
you how to build a firewall to meet your particular
requirements.</para>
@ -1591,9 +1591,9 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
<para>When initially setting up your firewall, unless you have a
test bench setup where you can configure your firewall host in a
controlled environment, I strongly recommend you use the logging
version of the commands and enable logging in the kernel. This
version of the commands and enable logging in the kernel. This
will allow you to quickly identify problem areas and cure them
without too much disruption. Even after the initial setup phase is
without too much disruption. Even after the initial setup phase is
complete, I recommend using the logging for of `deny' as it allows
tracing of possible attacks and also modification of the firewall
rules if your requirements alter.</para>
@ -1603,25 +1603,25 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
<emphasis>large</emphasis> amounts of log data as one log line
will be generated for every packet that passes through the
firewall, so large ftp/http transfers, etc, will really slow the
system down. It also increases the latencies on those packets as
system down. It also increases the latencies on those packets as
it requires more work to be done by the kernel before the packet
can be passed on. syslogd with also start using up a lot more
can be passed on. syslogd with also start using up a lot more
processor time as it logs all the extra data to disk, and it
could quite easily fill the partition
<filename>/var/log</filename> is located on.</para>
</note>
<para>As currently supplied, FreeBSD does not have the ability to
load firewall rules at boot time. My suggestion is to put a call
load firewall rules at boot time. My suggestion is to put a call
to a shell script in the <filename>/etc/netstart</filename>
script. Put the call early enough in the netstart file so that the
script. Put the call early enough in the netstart file so that the
firewall is configured before any of the IP interfaces are
configured. This means that there is no window during which time
configured. This means that there is no window during which time
your network is open.</para>
<para>The actual script used to load the rules is entirely up to
you. There is currently no support in the <command>ipfw</command> utility for loading multiple rules in
the one command. The system I use is to use the command:</para>
you. There is currently no support in the <command>ipfw</command> utility for loading multiple rules in
the one command. The system I use is to use the command:</para>
<screen>&prompt.root; <userinput>ipfw list</userinput></screen>
@ -1629,8 +1629,8 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
<para>to write a list of the current rules out to a file, and then
use a text editor to prepend <literal>ipfw
</literal> before all the lines. This will allow the script to
be fed into /bin/sh and reload the rules into the kernel. Perhaps
</literal> before all the lines. This will allow the script to
be fed into /bin/sh and reload the rules into the kernel. Perhaps
not the most efficient way, but it works.</para>
<para>The next problem is what your firewall should actually
@ -1650,33 +1650,33 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
<listitem>
<para>Block <emphasis>all</emphasis> incoming UDP
traffic. There are very few useful services that travel over
traffic. There are very few useful services that travel over
UDP, and what useful traffic there is is normally a security
threat (e.g. Suns RPC and NFS protocols). This has its
threat (e.g. Suns RPC and NFS protocols). This has its
disadvantages also, since UDP is a connectionless protocol,
denying incoming UDP traffic also blocks the replies to
outgoing UDP traffic. This can cause a problem for people
outgoing UDP traffic. This can cause a problem for people
(on the inside) using external archie (prospero) servers.
If you want to allow access to archie, you'll have to allow
packets coming from ports 191 and 1525 to any internal UDP
port through the firewall. ntp is another service you may
port through the firewall. ntp is another service you may
consider allowing through, which comes from port 123.</para>
</listitem>
<listitem>
<para>Block traffic to port 6000 from the outside. Port 6000
<para>Block traffic to port 6000 from the outside. Port 6000
is the port used for access to X11 servers, and can be a
security threat (especially if people are in the habit of
doing <command>xhost +</command> on their
workstations). X11 can actually use a range of ports
workstations). X11 can actually use a range of ports
starting at 6000, the upper limit being how many X displays
you can run on the machine. The upper limit as defined by
you can run on the machine. The upper limit as defined by
RFC 1700 (Assigned Numbers) is 6063.</para>
</listitem>
<listitem>
<para>Check what ports any internal servers use (e.g. SQL
servers, etc). It is probably a good idea to block those as
servers, etc). It is probably a good idea to block those as
well, as they normally fall outside the 1-1024 range
specified above.</para>
</listitem>
@ -1689,8 +1689,8 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
URL="ftp://ftp.cert.org/pub/tech_tips/packet_filtering">ftp://ftp.cert.org/pub/tech_tips/packet_filtering</ulink></para>
<para>As I said above, these are only
<emphasis>guidelines</emphasis>. You will have to decide what
filter rules you want to use on your firewall yourself. I cannot
<emphasis>guidelines</emphasis>. You will have to decide what
filter rules you want to use on your firewall yourself. I cannot
accept ANY responsibility if someone breaks into your network,
even if you follow the advice given above.</para>

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

File diff suppressed because it is too large Load diff

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

@ -87,7 +87,7 @@
<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
engineering work on the FreeBSD source tree. All core team members
are also developers.</para>