aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/handbook
diff options
context:
space:
mode:
Diffstat (limited to 'en_US.ISO8859-1/books/handbook')
-rw-r--r--en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml4826
-rw-r--r--en_US.ISO8859-1/books/handbook/audit/chapter.xml172
-rw-r--r--en_US.ISO8859-1/books/handbook/basics/chapter.xml525
-rw-r--r--en_US.ISO8859-1/books/handbook/boot/chapter.xml197
-rw-r--r--en_US.ISO8859-1/books/handbook/config/chapter.xml2450
-rw-r--r--en_US.ISO8859-1/books/handbook/disks/chapter.xml57
-rw-r--r--en_US.ISO8859-1/books/handbook/eresources/chapter.xml370
-rw-r--r--en_US.ISO8859-1/books/handbook/install/chapter.xml2643
-rw-r--r--en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml27
-rw-r--r--en_US.ISO8859-1/books/handbook/mac/chapter.xml250
-rw-r--r--en_US.ISO8859-1/books/handbook/mail/chapter.xml1678
-rw-r--r--en_US.ISO8859-1/books/handbook/multimedia/chapter.xml1514
-rw-r--r--en_US.ISO8859-1/books/handbook/network-servers/chapter.xml1265
-rw-r--r--en_US.ISO8859-1/books/handbook/ports/chapter.xml104
-rw-r--r--en_US.ISO8859-1/books/handbook/security/chapter.xml3513
-rw-r--r--en_US.ISO8859-1/books/handbook/users/chapter.xml45
16 files changed, 9519 insertions, 10117 deletions
diff --git a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml
index d402890e50..26dba92958 100644
--- a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml
+++ b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml
@@ -11,7 +11,7 @@
<sect1 id="advanced-networking-synopsis">
<title>Synopsis</title>
- <para>This chapter will cover a number of advanced networking
+ <para>This chapter covers a number of advanced networking
topics.</para>
<para>After reading this chapter, you will know:</para>
@@ -27,7 +27,7 @@
</listitem>
<listitem>
- <para>How to make FreeBSD act as a bridge.</para>
+ <para>How to make &os; act as a bridge.</para>
</listitem>
<listitem>
@@ -36,8 +36,9 @@
</listitem>
<listitem>
- <para>How to set up network PXE booting with an NFS root file
- system.</para>
+ <para>How to set up network <acronym>PXE</acronym> booting
+ with an
+ <acronym>NFS</acronym> root file system.</para>
</listitem>
<listitem>
@@ -45,16 +46,18 @@
</listitem>
<listitem>
- <para>How to set up IPv6 on a FreeBSD machine.</para>
+ <para>How to set up <acronym>IPv6</acronym> on a &os;
+ machine.</para>
</listitem>
<listitem>
- <para>How to configure ATM.</para>
+ <para>How to configure <acronym>ATM</acronym>.</para>
</listitem>
<listitem>
- <para>How to enable and utilize the features of CARP, the
- Common Address Redundancy Protocol in &os;</para>
+ <para>How to enable and utilize the features of the Common
+ Address Redundancy Protocol (<acronym>CARP</acronym>) in
+ &os;.</para>
</listitem>
</itemizedlist>
@@ -71,13 +74,13 @@
</listitem>
<listitem>
- <para>Know how to configure and install a new FreeBSD kernel
+ <para>Know how to configure and install a new &os; kernel
(<xref linkend="kernelconfig"/>).</para>
</listitem>
<listitem>
- <para>Know how to install additional third-party
- software (<xref linkend="ports"/>).</para>
+ <para>Know how to install additional third-party software
+ (<xref linkend="ports"/>).</para>
</listitem>
</itemizedlist>
@@ -105,22 +108,21 @@
one to the other. This is called
<firstterm>routing</firstterm>. A <quote>route</quote> is a
defined pair of addresses: a <quote>destination</quote> and a
- <quote>gateway</quote>. The pair indicates that if you are
- trying to get to this <emphasis>destination</emphasis>,
- communicate through this <emphasis>gateway</emphasis>. There
- are three types of destinations: individual hosts, subnets, and
+ <quote>gateway</quote>. The pair indicates that when trying
+ to get to this <emphasis>destination</emphasis>, communicate
+ through this <emphasis>gateway</emphasis>. There are three
+ types of destinations: individual hosts, subnets, and
<quote>default</quote>. The <quote>default route</quote> 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
+ used if none of the other routes apply. There are also three
types of gateways: individual hosts, interfaces (also called
- <quote>links</quote>), and Ethernet hardware addresses (MAC
- addresses).</para>
+ <quote>links</quote>), and Ethernet hardware
+ (<acronym>MAC</acronym>) addresses.</para>
<sect2>
<title>An Example</title>
- <para>To illustrate different aspects of routing, we will use
- the following example from <command>netstat</command>:</para>
+ <para>This example &man.netstat.1; output illustrates several
+ aspects of routing:</para>
<screen>&prompt.user; <userinput>netstat -r</userinput>
Routing tables
@@ -138,9 +140,8 @@ host2.example.com link#1 UC 0 0
224 link#1 UC 0 0</screen>
<indexterm><primary>default route</primary></indexterm>
- <para>The first two lines specify the default route (which we
- will cover in the
- <link linkend="network-routing-default">next section</link>)
+ <para>The first two lines specify the default route, described
+ in more detail in <xref linkend="network-routing-default"/>,
and the <hostid>localhost</hostid> route.</para>
<indexterm><primary>loopback device</primary></indexterm>
@@ -149,66 +150,60 @@ host2.example.com link#1 UC 0 0
<literal>localhost</literal> is <devicename>lo0</devicename>,
also known as the loopback device. This says to keep all
traffic for this destination internal, rather than sending it
- out over the LAN, since it will only end up back where it
- started.</para>
+ out over the network.</para>
<indexterm>
<primary>Ethernet</primary>
<secondary>MAC address</secondary>
</indexterm>
- <para>The next thing that stands out are the addresses beginning
- with <hostid role="mac">0:e0:</hostid>. These are Ethernet
- hardware addresses, which are also known as MAC addresses.
- FreeBSD will automatically identify any hosts
- (<hostid>test0</hostid> in the example) on the local Ethernet
- and add a route for that host, directly to it over the
- Ethernet interface, <devicename>ed0</devicename>. There is
- also a timeout (<literal>Expire</literal> column) associated
- with this type of route, which is used if we fail to hear from
- the host in a specific amount of time. When this happens, the
- route to this host will be automatically deleted. These hosts
- are identified using a mechanism known as RIP (Routing
- Information Protocol), which figures out routes to local hosts
- based upon a shortest path determination.</para>
+ <para>The addresses beginning with <hostid
+ role="mac">0:e0:</hostid> are Ethernet hardware addresses,
+ also known as <acronym>MAC</acronym> addresses. &os; will
+ automatically identify any hosts, <hostid>test0</hostid> in
+ the example, on the local Ethernet and add a route for that
+ host over the Ethernet interface,
+ <devicename>ed0</devicename>. This type of route has a
+ timeout, seen in the <literal>Expire</literal> column, which
+ is used if the host does not respond in a specific amount of
+ time. When this happens, the route to this host will be
+ automatically deleted. These hosts are identified using the
+ Routing Information Protocol (<acronym>RIP</acronym>), which
+ calculates routes to local hosts based upon a shortest path
+ determination.</para>
<indexterm><primary>subnet</primary></indexterm>
- <para>FreeBSD will also add subnet routes for the local subnet
- (<hostid role="ipaddr">10.20.30.255</hostid> is the broadcast
- address for the subnet
- <hostid role="ipaddr">10.20.30</hostid>, and
- <hostid role="domainname">example.com</hostid> is the domain
- name associated with that subnet). The designation
+ <para>&os; will add subnet routes for the local subnet.
+ <hostid role="ipaddr">10.20.30.255</hostid> is the broadcast
+ address for the subnet <hostid role="ipaddr">10.20.30</hostid>
+ and <hostid role="domainname">example.com</hostid> is the
+ domain name associated with that subnet. The designation
<literal>link#1</literal> refers to the first Ethernet card in
- the machine. You will notice no additional interface is
- specified for those.</para>
-
- <para>Both of these groups (local network hosts and local
- subnets) have their routes automatically configured by a
- daemon called <application>routed</application>. If this is
- not run, then only routes which are statically defined (i.e.,
- entered explicitly) will exist.</para>
-
- <para>The <literal>host1</literal> line refers to our host,
- which it knows by Ethernet address. Since we are the sending
- host, FreeBSD knows to use the loopback interface
- (<devicename>lo0</devicename>) rather than sending it out over
- the Ethernet interface.</para>
-
- <para>The two <literal>host2</literal> lines are an example of
- what happens when we use an &man.ifconfig.8; alias (see the
- section on Ethernet for reasons why we would do this). The
+ the machine.</para>
+
+ <para>Local network hosts and local subnets have their routes
+ automatically configured by a daemon called &man.routed.8;.
+ If it is not running, only routes which are statically defined
+ by the administrator will exist.</para>
+
+ <para>The <literal>host1</literal> line refers to the host
+ by its Ethernet address. Since it is the sending host, &os;
+ knows to use the loopback interface
+ (<devicename>lo0</devicename>) rather than the Ethernet
+ interface.</para>
+
+ <para>The two <literal>host2</literal> lines represent aliases
+ which were created using &man.ifconfig.8;. The
<literal>=&gt;</literal> symbol after the
- <devicename>lo0</devicename> interface says that not only are
- we using the loopback (since this address also refers to the
- local host), but specifically it is an alias. Such routes
+ <devicename>lo0</devicename> interface says that an alias
+ has been set in addition to the loopback address. Such routes
only show up on the host that supports the alias; all other
- hosts on the local network will simply have a
+ hosts on the local network will have a
<literal>link#1</literal> line for such routes.</para>
- <para>The final line (destination subnet
- <hostid role="ipaddr">224</hostid>) deals with multicasting,
- which will be covered in another section.</para>
+ <para>The final line (destination subnet <hostid
+ role="ipaddr">224</hostid>) deals with
+ multicasting.</para>
<para>Finally, various attributes of each route can be seen in
the <literal>Flags</literal> column. Below is a short table
@@ -247,7 +242,7 @@ host2.example.com link#1 UC 0 0
<row>
<entry>C</entry>
<entry>Clone: Generates a new route based upon this
- route for machines we connect to. This type of route
+ route for machines to connect to. This type of route
is normally used for local networks.</entry>
</row>
@@ -276,25 +271,24 @@ host2.example.com link#1 UC 0 0
<para>When the local system needs to make a connection to a
remote host, it checks the routing table to determine if a
known path exists. If the remote host falls into a subnet
- that we know how to reach (Cloned routes), then the system
- checks to see if it can connect along that interface.</para>
+ that it knows how to reach, the system checks to see if it
+ can connect using that interface.</para>
<para>If all known paths fail, the system has one last option:
the <quote>default</quote> route. This route is a special
type of gateway route (usually the only one present in the
system), and is always marked with a <literal>c</literal> in
the flags field. For hosts on a local area network, this
- gateway is set to whatever machine has a direct connection to
- the outside world (whether via PPP link, DSL, cable modem, T1,
- or another network interface).</para>
+ gateway is set to the system which has a direct connection to
+ the Internet.</para>
- <para>If you are configuring the default route for a machine
- which itself is functioning as the gateway to the outside
- world, then the default route will be the gateway machine at
- your Internet Service Provider's (ISP) site.</para>
+ <para>The default route for a machine which itself is
+ functioning as the gateway to the outside world, will be the
+ gateway machine at the Internet Service Provider
+ (<acronym>ISP</acronym>).</para>
- <para>Let us look at an example of default routes. This is a
- common configuration:</para>
+ <para>This example is a common configuration for a default
+ route:</para>
<mediaobject>
<imageobject>
@@ -308,14 +302,15 @@ host2.example.com link#1 UC 0 0
</mediaobject>
<para>The hosts <hostid>Local1</hostid> and
- <hostid>Local2</hostid> are at your site.
- <hostid>Local1</hostid> is connected to an ISP via a dial up
- PPP connection. This PPP server computer is connected through
- a local area network to another gateway computer through an
- external interface to the ISPs Internet feed.</para>
+ <hostid>Local2</hostid> are on the local network.
+ <hostid>Local1</hostid> is connected to an
+ <acronym>ISP</acronym> using a
+ <acronym>PPP</acronym> connection. This
+ <acronym>PPP</acronym> server is connected through a local
+ area network to another gateway computer through an external
+ interface to the <acronym>ISP</acronym>.</para>
- <para>The default routes for each of your machines will
- be:</para>
+ <para>The default routes for each machine will be:</para>
<informaltable frame="none" pgwide="1">
<tgroup cols="3">
@@ -343,26 +338,28 @@ host2.example.com link#1 UC 0 0
</tgroup>
</informaltable>
- <para>A common question is <quote>Why (or how) would we set
- the <hostid>T1-GW</hostid> to be the default gateway for
- <hostid>Local1</hostid>, rather than the ISP server it is
- connected to?</quote>.</para>
-
- <para>Remember, since the PPP interface is using an address on
- the ISP's local network for your side of the connection,
- routes for any other machines on the ISP's local network will
- be automatically generated. Hence, you will already know how
+ <para>A common question is <quote>Why is
+ <hostid>T1-GW</hostid> configured as the default gateway for
+ <hostid>Local1</hostid>, rather than the
+ <acronym>ISP</acronym> server it is connected
+ to?</quote>.</para>
+
+ <para>Since the <acronym>PPP</acronym> interface is using an
+ address on the <acronym>ISP</acronym>'s local network for
+ the local side of the connection, routes for any other
+ machines on the <acronym>ISP</acronym>'s local network will
+ be automatically generated. The system already knows how
to reach the <hostid>T1-GW</hostid> machine, so there is no
- need for the intermediate step of sending traffic to the ISP
- server.</para>
-
- <para>It is common to use the address
- <hostid role="ipaddr">X.X.X.1</hostid> as the gateway address
- for your local network. So (using the same example), if your
- local class-C address space was
- <hostid role="ipaddr">10.20.30</hostid> and your ISP was using
- <hostid role="ipaddr">10.9.9</hostid> then the default routes
- would be:</para>
+ need for the intermediate step of sending traffic to the
+ <acronym>ISP</acronym>'s server.</para>
+
+ <para>It is common to use the address <hostid
+ role="ipaddr">X.X.X.1</hostid> as the gateway address for
+ the local network. So, if the local class C address space is
+ <hostid role="ipaddr">10.20.30</hostid> and the
+ <acronym>ISP</acronym> is using <hostid
+ role="ipaddr">10.9.9</hostid>, the default routes would
+ be:</para>
<informaltable frame="none" pgwide="1">
<tgroup cols="2">
@@ -387,19 +384,19 @@ host2.example.com link#1 UC 0 0
</informaltable>
<para>The default route can be easily defined in
- <filename>/etc/rc.conf</filename>. In our example, on
- the <hostid>Local2</hostid> machine, we added the following
- line in <filename>/etc/rc.conf</filename>:</para>
+ <filename>/etc/rc.conf</filename>. In this example, on
+ <hostid>Local2</hostid>, add the following line to
+ <filename>/etc/rc.conf</filename>:</para>
<programlisting>defaultrouter="10.20.30.1"</programlisting>
- <para>It is also possible to do it directly from the command
- line with the &man.route.8; command:</para>
+ <para>It is also possible to add the route directly using
+ &man.route.8;:</para>
<screen>&prompt.root; <userinput>route add default 10.20.30.1</userinput></screen>
<para>For more information on manual manipulation of network
- routing tables, consult the &man.route.8; manual page.</para>
+ routing tables, refer to &man.route.8;.</para>
</sect2>
<sect2 id="network-dual-homed-hosts">
@@ -407,32 +404,27 @@ host2.example.com link#1 UC 0 0
<indexterm><primary>dual homed hosts</primary></indexterm>
- <para>There is one other type of configuration that we should
- cover, and that is a host that sits on two different networks.
- Technically, any machine functioning as a gateway (in the
- example above, using a PPP connection) counts as a dual-homed
- host. But the term is really only used to refer to a machine
- that sits on two local-area networks.</para>
-
- <para>In one case, the machine has two Ethernet cards, each
- having an address on the separate subnets. Alternately, the
- machine may only have one Ethernet card, and be using
- &man.ifconfig.8; 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>A a dual-homed system is a host which resides on two
+ different networks.</para>
+
+ <para>The dual-homed machine might have two Ethernet cards, each
+ having an address on a separate subnet. Alternately, the
+ machine can have one Ethernet card and uses &man.ifconfig.8;
+ aliasing. The former is used if two physically separate
+ Ethernet networks are in use and the latter if there is one
+ physical network segment, but two logically separate
+ subnets.</para>
<para>Either way, routing tables are set up so that each subnet
knows that this machine is the defined gateway (inbound route)
to the other subnet. This configuration, with the machine
- acting as a router between the two subnets, is often used when
- we need to implement packet filtering or firewall security in
+ acting as a router between the two subnets, is often used
+ to implement packet filtering or firewall security in
either or both directions.</para>
- <para>If you want this machine to actually forward packets
- between the two interfaces, you need to tell FreeBSD to enable
- this ability. See the next section for more details on how
- to do this.</para>
+ <para>For this machine to forward packets between the two
+ interfaces, &os; must be configured as a router, as
+ demonstrated in the next section.</para>
</sect2>
<sect2 id="network-dedicated-router">
@@ -440,10 +432,10 @@ host2.example.com link#1 UC 0 0
<indexterm><primary>router</primary></indexterm>
- <para>A network router is simply a system that forwards packets
- from one interface to another. Internet standards and good
- engineering practice prevent the FreeBSD Project from enabling
- this by default in FreeBSD. You can enable this feature by
+ <para>A network router is a system that forwards packets from
+ one interface to another. Internet standards and good
+ engineering practice prevent the &os; Project from enabling
+ this by default in &os;. This feature can be enabled by
changing the following variable to <literal>YES</literal> in
&man.rc.conf.5;:</para>
@@ -451,23 +443,21 @@ host2.example.com link#1 UC 0 0
<para>This option will set the &man.sysctl.8; variable
<varname>net.inet.ip.forwarding</varname> to
- <literal>1</literal>. If you should need to stop routing
- temporarily, you can reset this to <literal>0</literal>
- temporarily.</para>
+ <literal>1</literal>. To stop routing, reset this to
+ <literal>0</literal>.</para>
<indexterm><primary>BGP</primary></indexterm>
<indexterm><primary>RIP</primary></indexterm>
<indexterm><primary>OSPF</primary></indexterm>
- <para>Your new router will need routes to know where to send the
- traffic. If your network is simple enough you can use static
- routes. FreeBSD also comes with the standard BSD routing
- daemon &man.routed.8;, which speaks RIP (both version 1 and
- version 2) and IRDP. Support for BGP v4, OSPF v2, and other
+ <para>The new router will need routes to know where to send the
+ traffic. If the network is simple enough, static routes can
+ be used. &os; comes with the standard BSD routing daemon
+ &man.routed.8;, which speaks <acronym>RIP</acronym> versions
+ 1 and 2, and <acronym>IRDP</acronym>. Support for
+ <acronym>BGP</acronym>v4, <acronym>OSPF</acronym>v2, and other
sophisticated routing protocols is available with the
- <filename role="package">net/zebra</filename> package.
- Commercial products such as <application>&gated;</application>
- are also available for more complex network routing
- solutions.</para>
+ <filename role="package">net/zebra</filename> package or
+ port.</para>
</sect2>
<sect2 id="network-static-routes">
@@ -486,7 +476,7 @@ host2.example.com link#1 UC 0 0
<sect3>
<title>Manual Configuration</title>
- <para>Let us assume we have a network as follows:</para>
+ <para>Consider the following network:</para>
<mediaobject>
<imageobject>
@@ -520,21 +510,16 @@ host2.example.com link#1 UC 0 0
</textobject>
</mediaobject>
- <para>In this scenario, <hostid>RouterA</hostid> is our &os;
+ <para>In this scenario, <hostid>RouterA</hostid> is a &os;
machine that is acting as a router to the rest of the
- Internet. It has a default route set to
- <hostid role="ipaddr">10.0.0.1</hostid> which allows it to
- connect with the outside world. We will assume that
- <hostid>RouterB</hostid> is already configured properly and
- knows how to get wherever it needs to go. (This is simple
- in this picture. Just add a default route on
- <hostid>RouterB</hostid> using
- <hostid role="ipaddr">192.168.1.1</hostid> as the
- gateway.)</para>
-
- <para>If we look at the routing table for
- <hostid>RouterA</hostid> we would see something like the
- following:</para>
+ Internet. It has a default route set to <hostid
+ role="ipaddr">10.0.0.1</hostid> which allows it to
+ connect with the outside world. <hostid>RouterB</hostid> is
+ already configured properly as it uses <hostid
+ role="ipaddr">192.168.1.1</hostid> as the gateway.</para>
+
+ <para>The routing table on <hostid>RouterA</hostid> looks
+ something like this:</para>
<screen>&prompt.user; <userinput>netstat -nr</userinput>
Routing tables
@@ -546,14 +531,12 @@ default 10.0.0.1 UGS 0 49378 xl0
10.0.0.0/24 link#1 UC 0 0 xl0
192.168.1.0/24 link#2 UC 0 0 xl1</screen>
- <para>With the current routing table <hostid>RouterA</hostid>
- will not be able to reach our Internal Net 2. It does not
- have a route for
- <hostid role="ipaddr">192.168.2.0/24</hostid>. One way to
- alleviate this is to manually add the route. The following
- command would add the Internal Net 2 network to
- <hostid>RouterA</hostid>'s routing table using
- <hostid role="ipaddr">192.168.1.2</hostid> as the next
+ <para>With the current routing table, <hostid>RouterA</hostid>
+ cannot reach Internal Net 2 as it does not have a route for
+ <hostid role="ipaddr">192.168.2.0/24</hostid>. The
+ following command adds the Internal Net 2 network to
+ <hostid>RouterA</hostid>'s routing table using <hostid
+ role="ipaddr">192.168.1.2</hostid> as the next
hop:</para>
<screen>&prompt.root; <userinput>route add -net 192.168.2.0/24 192.168.1.2</userinput></screen>
@@ -566,39 +549,34 @@ default 10.0.0.1 UGS 0 49378 xl0
<sect3>
<title>Persistent Configuration</title>
- <para>The above example is perfect for configuring a static
- route on a running system. However, one problem is that the
- routing information will not persist if you reboot your &os;
- machine. Additional static routes can be
- entered in <filename>/etc/rc.conf</filename>:</para>
+ <para>The above example configures a static route on a
+ running system. However, the routing information will not
+ persist if the &os; system reboots. Persistent static
+ routes can be entered in
+ <filename>/etc/rc.conf</filename>:</para>
<programlisting># Add Internal Net 2 as a static route
static_routes="internalnet2"
route_internalnet2="-net 192.168.2.0/24 192.168.1.2"</programlisting>
<para>The <literal>static_routes</literal> configuration
- variable is a list of strings separated by a space. Each
- string references to a route name. In our above example we
- only have one string in <literal>static_routes</literal>.
- This string is <replaceable>internalnet2</replaceable>. We
- then add a configuration variable called
+ variable is a list of strings separated by a space, where
+ each string references a route name. This example only
+ has one string in <literal>static_routes</literal>,
+ <replaceable>internalnet2</replaceable>. The variable
<literal>route_<replaceable>internalnet2</replaceable></literal>
- where we put all of the configuration parameters we would
- give to the &man.route.8; command. For our example above we
- would have used the command:</para>
+ contains all of the configuration parameters to
+ &man.route.8;. This example is equivalent to the
+ command:</para>
<screen>&prompt.root; <userinput>route add -net 192.168.2.0/24 192.168.1.2</userinput></screen>
- <para>so we need <literal>"-net 192.168.2.0/24
- 192.168.1.2"</literal>.</para>
-
- <para>As said above, we can have more than one string in
- <literal>static_routes</literal>. This allows us to create
- multiple static routes. The following lines shows an
- example of adding static routes for the
- <hostid role="ipaddr">192.168.0.0/24</hostid> and
- <hostid role="ipaddr">192.168.1.0/24</hostid> networks on an
- imaginary router:</para>
+ <para>Using more than one string in
+ <literal>static_routes</literal> creates multiple static
+ routes. The following shows an example of adding static
+ routes for the <hostid role="ipaddr">192.168.0.0/24</hostid>
+ and <hostid role="ipaddr">192.168.1.0/24</hostid>
+ networks:</para>
<programlisting>static_routes="net1 net2"
route_net1="-net 192.168.0.0/24 192.168.0.1"
@@ -609,36 +587,24 @@ route_net2="-net 192.168.1.0/24 192.168.1.1"</programlisting>
<sect2 id="network-routing-propagation">
<title>Routing Propagation</title>
- <indexterm><primary>routing propagation</primary></indexterm>
- <para>We have already talked about how we define our routes to
- the outside world, but not about how the outside world finds
- us.</para>
-
- <para>We already know that routing tables can be set up so that
- all traffic for a particular address space (in our examples, a
- class-C subnet) can be sent to a particular host on that
- network, which will forward the packets inbound.</para>
-
- <para>When you get an address space assigned to your site, your
- service provider will set up their routing tables so that all
- traffic for your subnet will be sent down your PPP link to
- your site. But how do sites across the country know to send
- to your ISP?</para>
-
- <para>There is a system (much like the distributed DNS
- information) that keeps track of all assigned address-spaces,
- and defines their point of connection to the Internet
- Backbone. The <quote>Backbone</quote> are the main trunk
- lines that carry Internet traffic across the country, and
- around the world. Each backbone machine has a copy of a
- master set of tables, which direct traffic for a particular
- network to a specific backbone carrier, and from there down
- the chain of service providers until it reaches your
- network.</para>
-
- <para>It is the task of your service provider to advertise to
- the backbone sites that they are the point of connection (and
- thus the path inward) for your site. This is known as route
+ <para>When an address space is assigned to a network, the
+ service provider configures their routing tables so that all
+ traffic for the network will be sent to the link for the
+ site. But how do external sites know to send their packets
+ to the network's <acronym>ISP</acronym>?</para>
+
+ <para>There is a system that keeps track of all assigned
+ address spaces and defines their point of connection to the
+ Internet backbone, or the main trunk lines that carry Internet
+ traffic across the country and around the world. Each
+ backbone machine has a copy of a master set of tables, which
+ direct traffic for a particular network to a specific
+ backbone carrier, and from there down the chain of service
+ providers until it reaches your network.</para>
+
+ <para>It is the task of the service provider to advertise to
+ the backbone sites that they are the point of connection, and
+ thus the path inward, for a site. This is known as route
propagation.</para>
</sect2>
@@ -646,24 +612,22 @@ route_net2="-net 192.168.1.0/24 192.168.1.1"</programlisting>
<title>Troubleshooting</title>
<indexterm>
- <primary><command>traceroute</command></primary>
+ <primary>&man.traceroute.8;</primary>
</indexterm>
- <para>Sometimes, there is a problem with routing propagation,
- and some sites are unable to connect to you. Perhaps the most
+ <para>Sometimes, there is a problem with routing propagation
+ and some sites are unable to connect. Perhaps the most
useful command for trying to figure out where routing is
- breaking down is the &man.traceroute.8; command. It is
- equally useful if you cannot seem to make a connection to a
- remote machine (i.e., &man.ping.8; fails).</para>
+ breaking down is &man.traceroute.8;. It is useful when
+ &man.ping.8; fails.</para>
- <para>The &man.traceroute.8; command is run with the name of the
- remote host you are trying to connect to. It will show the
- gateway hosts along the path of the attempt, eventually either
+ <para>When using &man.traceroute.8;, include the name of the
+ remote host to connect to. The output will show the gateway
+ hosts along the path of the attempt, eventually either
reaching the target host, or terminating because of a lack of
connection.</para>
- <para>For more information, see the manual page for
- &man.traceroute.8;.</para>
+ <para>For more information, refer to &man.traceroute.8;.</para>
</sect2>
<sect2 id="network-routing-multicast">
@@ -676,19 +640,18 @@ route_net2="-net 192.168.1.0/24 192.168.1.1"</programlisting>
<primary>kernel options</primary>
<secondary>MROUTING</secondary>
</indexterm>
- <para>FreeBSD supports both multicast applications and multicast
- routing natively. Multicast applications do not require any
- special configuration of FreeBSD; applications will generally
- run out of the box. Multicast routing
- requires that support be compiled into the kernel:</para>
+ <para>&os; natively supports both multicast applications and
+ multicast routing. Multicast applications do not require any
+ special configuration of &os;; as applications will generally
+ run out of the box. Multicast routing requires that support
+ be compiled into a custom kernel:</para>
<programlisting>options MROUTING</programlisting>
- <para>In addition, the multicast routing daemon, &man.mrouted.8;
- must be configured to set up tunnels and
- <acronym>DVMRP</acronym> via
+ <para>The multicast routing daemon, &man.mrouted.8;, must be
+ configured to set up tunnels and <acronym>DVMRP</acronym> via
<filename>/etc/mrouted.conf</filename>. More details on
- multicast configuration may be found in the manual page for
+ multicast configuration may be found in
&man.mrouted.8;.</para>
<note>
@@ -697,8 +660,8 @@ route_net2="-net 192.168.1.0/24 192.168.1.1"</programlisting>
which has largely been replaced by &man.pim.4; in many
multicast installations. &man.mrouted.8; and the related
&man.map-mbone.8; and &man.mrinfo.8; utilities are available
- in the &os; Ports&nbsp;Collection as
- <filename role="package">net/mrouted</filename>.</para>
+ in the &os; Ports&nbsp;Collection as <filename
+ role="package">net/mrouted</filename>.</para>
</note>
</sect2>
</sect1>
@@ -735,83 +698,92 @@ route_net2="-net 192.168.1.0/24 192.168.1.1"</programlisting>
<para>Most wireless networks are based on the &ieee; 802.11
standards. A basic wireless network consists of multiple
stations communicating with radios that broadcast in either
- the 2.4GHz or 5GHz band (though this varies according to the
+ the 2.4GHz or 5GHz band, though this varies according to the
locale and is also changing to enable communication in the
- 2.3GHz and 4.9GHz ranges).</para>
-
- <para>802.11 networks are organized in two ways: in
- <emphasis>infrastructure mode</emphasis> one station acts as a
- master with all the other stations associating to it; the
- network is known as a BSS and the master station is termed an
- access point (AP). In a BSS all communication passes through
- the AP; even when one station wants to communicate with
- another wireless station messages must go through the AP. In
- the second form of network there is no master and stations
- communicate directly. This form of network is termed an IBSS
- and is commonly known as an
- <emphasis>ad-hoc network</emphasis>.</para>
+ 2.3GHz and 4.9GHz ranges.</para>
+
+ <para>802.11 networks are organized in two ways. In
+ <emphasis>infrastructure mode</emphasis>, one station acts as
+ a
+ master with all the other stations associating to it, the
+ network is known as a <acronym>BSS</acronym>, and the master
+ station is termed an access point (<acronym>AP</acronym>).
+ In a <acronym>BSS</acronym>, all communication passes through
+ the <acronym>AP</acronym>; even when one station wants to
+ communicate with another wireless station, messages must go
+ through the <acronym>AP</acronym>. In the second form of
+ network, there is no master and stations communicate directly.
+ This form of network is termed an <acronym>IBSS</acronym>
+ and is commonly known as an <emphasis>ad-hoc
+ network</emphasis>.</para>
<para>802.11 networks were first deployed in the 2.4GHz band
using protocols defined by the &ieee; 802.11 and 802.11b
standard. These specifications include the operating
- frequencies, MAC layer characteristics including framing and
- transmission rates (communication can be done at various
- rates). Later the 802.11a standard defined operation in the
- 5GHz band, including different signalling mechanisms and
- higher transmission rates. Still later the 802.11g standard
- was defined to enable use of 802.11a signalling and
- transmission mechanisms in the 2.4GHz band in such a way as to
- be backwards compatible with 802.11b networks.</para>
-
- <para>Separate from the underlying transmission techniques
+ frequencies and the <acronym>MAC</acronym> layer
+ characteristics, including framing and transmission rates,
+ as communication can occur at various rates. Later, the
+ 802.11a standard defined operation in the 5GHz band, including
+ different signaling mechanisms and higher transmission rates.
+ Still later, the 802.11g standard defined the use of 802.11a
+ signaling and transmission mechanisms in the 2.4GHz band in
+ such a way as to be backwards compatible with 802.11b
+ networks.</para>
+
+ <para>Separate from the underlying transmission techniques,
802.11 networks have a variety of security mechanisms. The
original 802.11 specifications defined a simple security
- protocol called WEP. This protocol uses a fixed pre-shared key
- and the RC4 cryptographic cipher to encode data transmitted on
- a network. Stations must all agree on the fixed key in order
- to communicate. This scheme was shown to be easily broken and
- is now rarely used except to discourage transient users from
- joining networks. Current security practice is given by the
- &ieee; 802.11i specification that defines new cryptographic
- ciphers and an additional protocol to authenticate stations to
- an access point and exchange keys for doing data
- communication. Further, cryptographic keys are periodically
- refreshed and there are mechanisms for detecting intrusion
- attempts (and for countering intrusion attempts). Another
+ protocol called <acronym>WEP</acronym>. This protocol uses a
+ fixed pre-shared key and the RC4 cryptographic cipher to
+ encode data transmitted on a network. Stations must all
+ agree on the fixed key in order to communicate. This scheme
+ was shown to be easily broken and is now rarely used except
+ to discourage transient users from joining networks. Current
+ security practice is given by the &ieee; 802.11i specification
+ that defines new cryptographic ciphers and an additional
+ protocol to authenticate stations to an access point and
+ exchange keys for data communication. Cryptographic keys
+ are periodically refreshed and there are mechanisms for
+ detecting and countering intrusion attempts. Another
security protocol specification commonly used in wireless
- networks is termed WPA. This was a precursor to 802.11i
- defined by an industry group as an interim measure while
- waiting for 802.11i to be ratified. WPA specifies a subset of
- the requirements found in 802.11i and is designed for
- implementation on legacy hardware. Specifically WPA requires
- only the TKIP cipher that is derived from the original WEP
- cipher. 802.11i permits use of TKIP but also requires support
- for a stronger cipher, AES-CCM, for encrypting data. (The AES
- cipher was not required in WPA because it was deemed too
+ networks is termed <acronym>WPA</acronym>, which was a
+ precursor to 802.11i. <acronym>WPA</acronym> specifies a
+ subset of the requirements found in 802.11i and is designed
+ for implementation on legacy hardware. Specifically,
+ <acronym>WPA</acronym> requires only the
+ <acronym>TKIP</acronym> cipher that is derived from the
+ original <acronym>WEP</acronym> cipher. 802.11i permits use
+ of <acronym>TKIP</acronym> but also requires support for a
+ stronger cipher, AES-CCM, for encrypting data. The
+ <acronym>AES</acronym> cipher was not required in
+ <acronym>WPA</acronym> because it was deemed too
computationally costly to be implemented on legacy
- hardware.)</para>
-
- <para>Other than the above protocol standards the other
- important standard to be aware of is 802.11e. This defines
- protocols for deploying multi-media applications such as
- streaming video and voice over IP (VoIP) in an 802.11 network.
- Like 802.11i, 802.11e also has a precursor specification
- termed WME (later renamed WMM) that has been defined by an
+ hardware.</para>
+
+ <para>The other standard to be aware of is 802.11e. It defines
+ protocols for deploying multimedia applications, such as
+ streaming video and voice over IP (<acronym>VoIP</acronym>),
+ in an 802.11 network. Like 802.11i, 802.11e also has a
+ precursor specification termed <acronym>WME</acronym> (later
+ renamed <acronym>WMM</acronym>) that has been defined by an
industry group as a subset of 802.11e that can be deployed now
- to enable multi-media applications while waiting for the final
+ to enable multimedia applications while waiting for the final
ratification of 802.11e. The most important thing to know
- about 802.11e and WME/WMM is that it enables prioritized
- traffic use of a wireless network through Quality of Service
- (QoS) protocols and enhanced media access protocols. Proper
- implementation of these protocols enable high speed bursting
- of data and prioritized traffic flow.</para>
-
- <para>&os; supports networks that operate
- using 802.11a, 802.11b, and 802.11g. The WPA and 802.11i
+ about 802.11e and
+ <acronym>WME</acronym>/<acronym>WMM</acronym> is that it
+ enables prioritized traffic over a wireless network through
+ Quality of Service (<acronym>QoS</acronym>) protocols and
+ enhanced media access protocols. Proper implementation of
+ these protocols enables high speed bursting of data and
+ prioritized traffic flow.</para>
+
+ <para>&os; supports networks that operate using 802.11a,
+ 802.11b, and 802.11g. The <acronym>WPA</acronym> and 802.11i
security protocols are likewise supported (in conjunction with
- any of 11a, 11b, and 11g) and QoS and traffic prioritization
- required by the WME/WMM protocols are supported for a limited
- set of wireless devices.</para>
+ any of 11a, 11b, and 11g) and <acronym>QoS</acronym> and
+ traffic prioritization required by the
+ <acronym>WME</acronym>/<acronym>WMM</acronym> protocols are
+ supported for a limited set of wireless devices.</para>
</sect2>
<sect2 id="network-wireless-basic">
@@ -820,63 +792,59 @@ route_net2="-net 192.168.1.0/24 192.168.1.1"</programlisting>
<sect3>
<title>Kernel Configuration</title>
- <para>To use wireless networking, you need a wireless
- networking card and to configure the kernel with the
- appropriate wireless networking support. The latter is
- separated into multiple modules so that you only need to
- configure the software you are actually going to use.</para>
+ <para>To use wireless networking, a wireless networking card
+ is needed and the kernel needs to be configured with the
+ appropriate wireless networking support. The kernel is
+ separated into multiple modules so that only the required
+ support needs to be configured.</para>
- <para>The first thing you need is a wireless device. The most
- commonly used devices are those that use parts made by
- Atheros. These devices are supported by the &man.ath.4;
- driver and require the following line to be added to
+ <para>The most
+ commonly used wireless devices are those that use parts made
+ by Atheros. These devices are supported by &man.ath.4;
+ and require the following line to be added to
<filename>/boot/loader.conf</filename>:</para>
<programlisting>if_ath_load="YES"</programlisting>
<para>The Atheros driver is split up into three separate
- pieces: the proper driver (&man.ath.4;), the hardware
- support layer that handles chip-specific functions
- (&man.ath.hal.4;), and an algorithm for selecting which of
- several possible rates for transmitting frames
- (ath_rate_sample here). When this support is loaded as
- kernel modules, these dependencies are automatically handled
- for you. If, instead of an Atheros device, you had another
- device you would select the module for that device;
- e.g.:</para>
+ pieces: the driver (&man.ath.4;), the hardware support
+ layer that handles chip-specific functions
+ (&man.ath.hal.4;), and an algorithm for selecting the
+ rate for transmitting frames. When this support is loaded
+ as kernel modules, any dependencies are automatically
+ handled. To load support for a different type of wireless
+ device, specify the module for that device. This example
+ is for devices based on the Intersil Prism parts
+ (&man.wi.4;) driver:</para>
<programlisting>if_wi_load="YES"</programlisting>
- <para>for devices based on the Intersil Prism parts
- (&man.wi.4; driver).</para>
-
<note>
- <para>In the rest of this document, we will use an
- &man.ath.4; device, the device name in the examples must
- be changed according to your configuration. A list of
+ <para>The examples in this section use an &man.ath.4;
+ device and the device name in the examples must be
+ changed according to the configuration. A list of
available wireless drivers and supported adapters can be
- found in the &os; Hardware Notes. Copies of these notes
- for various releases and architectures are available on
+ found in the &os; Hardware Notes, available on
the <ulink
url="http://www.FreeBSD.org/releases/index.html">Release
- Information</ulink> page of the &os; Web site. If a
- native &os; driver for your wireless device does not
- exist, it may be possible to directly use the &windows;
- driver with the help of the
- <link linkend="config-network-ndis">NDIS</link> driver
+ Information</ulink> page of the &os; website. If a
+ native &os; driver for the wireless device does not
+ exist, it may be possible to use the &windows; driver
+ with the help of the <link
+ linkend="config-network-ndis">NDIS</link> driver
wrapper.</para>
</note>
- <para>With that, you will need the modules that implement
- cryptographic support for the security protocols you intend
- to use. These are intended to be dynamically loaded on
- demand by the &man.wlan.4; module but for now they must be
- manually configured. The following modules are available:
- &man.wlan.wep.4;, &man.wlan.ccmp.4; and &man.wlan.tkip.4;.
- Both &man.wlan.ccmp.4; and &man.wlan.tkip.4; drivers are
- only needed if you intend to use the WPA and/or 802.11i
- security protocols. If your network does not use
- encryption, you will not need &man.wlan.wep.4; support. To
+ <para>In addition, the modules that implement cryptographic
+ support for the security protocols to use must be loaded.
+ These are intended to be dynamically loaded on demand by
+ the &man.wlan.4; module, but for now they must be manually
+ configured. The following modules are available:
+ &man.wlan.wep.4;, &man.wlan.ccmp.4;, and &man.wlan.tkip.4;.
+ The &man.wlan.ccmp.4; and &man.wlan.tkip.4; drivers are
+ only needed when using the <acronym>WPA</acronym> or
+ 802.11i security protocols. If the network does not use
+ encryption, &man.wlan.wep.4; support is not needed. To
load these modules at boot time, add the following lines to
<filename>/boot/loader.conf</filename>:</para>
@@ -884,17 +852,16 @@ route_net2="-net 192.168.1.0/24 192.168.1.1"</programlisting>
wlan_ccmp_load="YES"
wlan_tkip_load="YES"</programlisting>
- <para>With this information in the system bootstrap
- configuration file (i.e.,
- <filename>/boot/loader.conf</filename>), you have to reboot
- your &os; box. If you do not want to reboot your machine
- for the moment, you can load the modules by hand using
+ <para>Once this information has been added to
+ <filename>/boot/loader.conf</filename>, reboot the &os;
+ box. Alternately, load the modules by hand using
&man.kldload.8;.</para>
<note>
- <para>If you do not want to use modules, it is possible to
- compile these drivers into the kernel by adding the
- following lines to your kernel configuration file:</para>
+ <para>For users who do not want to use modules, it is
+ possible to compile these drivers into the kernel by
+ adding the following lines to a custom kernel
+ configuration file:</para>
<programlisting>device wlan # 802.11 support
device wlan_wep # 802.11 WEP support
@@ -907,13 +874,12 @@ options AH_SUPPORT_AR5416 # enable AR5416 tx/rx descriptors
device ath_rate_sample # SampleRate tx rate control for ath</programlisting>
<para>With this information in the kernel configuration
- file, recompile the kernel and reboot your &os;
+ file, recompile the kernel and reboot the &os;
machine.</para>
</note>
- <para>When the system is up, we could find some information
- about the wireless device in the boot messages, like
- this:</para>
+ <para>Information about the wireless device should appear
+ in the boot messages, like this:</para>
<screen>ath0: &lt;Atheros 5212&gt; mem 0x88000000-0x8800ffff irq 11 at device 0.0 on cardbus1
ath0: [ITHREAD]
@@ -924,12 +890,12 @@ ath0: AR2413 mac 7.9 RF2413 phy 4.5</screen>
<sect2>
<title>Infrastructure Mode</title>
- <para>The infrastructure mode or BSS mode is the mode that is
- typically used. In this mode, a number of wireless access
- points are connected to a wired network. Each wireless
- network has its own name, this name is called the SSID of the
- network. Wireless clients connect to the wireless access
- points.</para>
+ <para>Infrastructure (<acronym>BSS</acronym>) mode is the
+ mode that is typically used. In this mode, a number of
+ wireless access points are connected to a wired network.
+ Each wireless network has its own name, called the
+ <acronym>SSID</acronym>. Wireless clients connect to the
+ wireless access points.</para>
<sect3>
<title>&os; Clients</title>
@@ -937,12 +903,11 @@ ath0: AR2413 mac 7.9 RF2413 phy 4.5</screen>
<sect4>
<title>How to Find Access Points</title>
- <para>To scan for networks, use the
- <command>ifconfig</command> command. This request may
- take a few moments to complete as it requires that the
- system switches to each available wireless frequency and
- probes for available access points. Only the super-user
- can initiate such a scan:</para>
+ <para>To scan for available networks, use &man.ifconfig.8;.
+ This request may take a few moments to complete as it
+ requires the system to switch to each available wireless
+ frequency and probe for available access points. Only
+ the superuser can initiate a scan:</para>
<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput>
&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> up scan</userinput>
@@ -951,18 +916,20 @@ dlinkap 00:13:46:49:41:76 11 54M -90:96 100 EPS WPA WME
freebsdap 00:11:95:c3:0d:ac 1 54M -83:96 100 EPS WPA</screen>
<note>
- <para>You must mark the interface <option>up</option>
- before you can scan. Subsequent scan requests do not
- require you to mark the interface up again.</para>
+ <para>The interface must be <option>up</option> before
+ it can scan. Subsequent scan requests do not require
+ the interface to be marked as up again.</para>
</note>
- <para>The output of a scan request lists each BSS/IBSS
- network found. Beside the name of the network,
- <literal>SSID</literal>, we find the
- <literal>BSSID</literal> which is the MAC address of the
- access point. The <literal>CAPS</literal> field
- identifies the type of each network and the capabilities
- of the stations operating there:</para>
+ <para>The output of a scan request lists each
+ <acronym>BSS</acronym>/<acronym>IBSS</acronym> network
+ found. Besides listing the name of the network, the
+ <literal>SSID</literal>, the output also shows the
+ <literal>BSSID</literal>, which is the
+ <acronym>MAC</acronym> address of the access point. The
+ <literal>CAPS</literal> field identifies the type of
+ each network and the capabilities of the stations
+ operating there:</para>
<table frame="none" pgwide="0">
<title>Station Capability Codes</title>
@@ -978,35 +945,38 @@ freebsdap 00:11:95:c3:0d:ac 1 54M -83:96 100 EPS WPA</screen>
<tbody>
<row>
<entry><literal>E</literal></entry>
- <entry>Extended Service Set (ESS). Indicates that
+ <entry>Extended Service Set
+ (<acronym>ESS</acronym>). Indicates that
the station is part of an infrastructure network
- (in contrast to an IBSS/ad-hoc network).</entry>
+ rather than an <acronym>IBSS</acronym>/ad-hoc
+ network.</entry>
</row>
<row>
<entry><literal>I</literal></entry>
- <entry>IBSS/ad-hoc network. Indicates that the
- station is part of an ad-hoc network (in contrast
- to an ESS network).</entry>
+ <entry><acronym>IBSS</acronym>/ad-hoc network.
+ Indicates that the station is part of an ad-hoc
+ network rather than an <acronym>ESS</acronym>
+ network.</entry>
</row>
<row>
<entry><literal>P</literal></entry>
- <entry>Privacy. Data confidentiality is required
- for all data frames exchanged within the BSS.
- This means that this BSS requires the station to
- use cryptographic means such as WEP, TKIP or
- AES-CCMP to encrypt/decrypt data frames being
- exchanged with others.</entry>
+ <entry>Privacy. Encryption is required for all
+ data frames exchanged within the
+ <acronym>BSS</acronym> using cryptographic means
+ such as <acronym>WEP</acronym>,
+ <acronym>TKIP</acronym> or
+ <acronym>AES</acronym>-<acronym>CCMP</acronym>.</entry>
</row>
<row>
<entry><literal>S</literal></entry>
<entry>Short Preamble. Indicates that the network
- is using short preambles (defined in 802.11b High
- Rate/DSSS PHY, short preamble utilizes a 56 bit
- sync field in contrast to a 128 bit field used in
- long preamble mode).</entry>
+ is using short preambles, defined in 802.11b High
+ Rate/DSSS PHY, and utilizes a 56 bit sync field
+ rather than the 128 bit field used in long
+ preamble mode.</entry>
</row>
<row>
@@ -1036,132 +1006,138 @@ freebsdap 00:11:95:c3:0d:ac 1 54M -83:96 100 EPS WPA</screen>
<para>This section provides a simple example of how to make
the wireless network adapter work in &os; without
- encryption. After you are familiar with these concepts,
- we strongly recommend using
- <link linkend="network-wireless-wpa">WPA</link> to set up
- your wireless network.</para>
+ encryption. Once familiar with these concepts, it is
+ strongly recommend to use <link
+ linkend="network-wireless-wpa">WPA</link> to set up
+ the wireless network.</para>
<para>There are three basic steps to configure a wireless
- network: selecting an access point, authenticating your
- station, and configuring an IP address. The following
- sections discuss each step.</para>
+ network: select an access point, authenticate the
+ station, and configure an <acronym>IP</acronym> address.
+ The following sections discuss each step.</para>
<sect5>
<title>Selecting an Access Point</title>
- <para>Most of time it is sufficient to let the system
+ <para>Most of the time, it is sufficient to let the system
choose an access point using the builtin heuristics.
- This is the default behaviour when you mark an interface
- up or otherwise configure an interface by listing it in
- <filename>/etc/rc.conf</filename>, e.g.:</para>
+ This is the default behaviour when an interface is
+ marked as up or it is listed in
+ <filename>/etc/rc.conf</filename>:</para>
<programlisting>wlans_ath0="wlan0"
ifconfig_wlan0="DHCP"</programlisting>
- <para>If there are multiple access points and you want to
- select a specific one, you can select it by its
- SSID:</para>
+ <para>If there are multiple access points, a specific
+ one can be selected by its
+ <acronym>SSID</acronym>:</para>
<programlisting>wlans_ath0="wlan0"
ifconfig_wlan0="ssid <replaceable>your_ssid_here</replaceable> DHCP"</programlisting>
<para>In an environment where there are multiple access
- points with the same SSID (often done to simplify
- roaming) it may be necessary to associate to one
- specific device. In this case you can also specify the
- BSSID of the access point (you can also leave off the
- SSID):</para>
+ points with the same <acronym>SSID</acronym>, which
+ is often done to simplify roaming, it may be necessary
+ to associate to one specific device. In this case, the
+ <acronym>BSSID</acronym> of the access point can be
+ specified, with or without the
+ <acronym>SSID</acronym>:</para>
<programlisting>wlans_ath0="wlan0"
ifconfig_wlan0="ssid <replaceable>your_ssid_here</replaceable> bssid <replaceable>xx:xx:xx:xx:xx:xx</replaceable> DHCP"</programlisting>
<para>There are other ways to constrain the choice of an
- access point such as limiting the set of frequencies the
- system will scan on. This may be useful if you have a
+ access point, such as limiting the set of frequencies
+ the system will scan on. This may be useful for a
multi-band wireless card as scanning all the possible
channels can be time-consuming. To limit operation to a
- specific band you can use the <option>mode</option>
- parameter; e.g.:</para>
+ specific band, use the <option>mode</option>
+ parameter:</para>
<programlisting>wlans_ath0="wlan0"
ifconfig_wlan0="mode <replaceable>11g</replaceable> ssid <replaceable>your_ssid_here</replaceable> DHCP"</programlisting>
- <para>will force the card to operate in 802.11g which is
- defined only for 2.4GHz frequencies so any 5GHz channels
- will not be considered. Other ways to do this are the
- <option>channel</option> parameter, to lock operation to
- one specific frequency, and the
+ <para>This example will force the card to operate in
+ 802.11g, which is defined only for 2.4GHz frequencies
+ so any 5GHz channels will not be considered. This can
+ also be achieved with the
+ <option>channel</option> parameter, which locks
+ operation to one specific frequency, and the
<option>chanlist</option> parameter, to specify a list
of channels for scanning. More information about these
- parameters can be found in the &man.ifconfig.8; manual
- page.</para>
+ parameters can be found in &man.ifconfig.8;.</para>
</sect5>
<sect5>
<title>Authentication</title>
- <para>Once you have selected an access point your station
+ <para>Once an access point is selected, the station
needs to authenticate before it can pass data.
Authentication can happen in several ways. The most
- common scheme used is termed open authentication and
- allows any station to join the network and communicate.
- This is the authentication you should use for test
- purpose the first time you set up a wireless network.
- Other schemes require cryptographic handshakes be
- completed before data traffic can flow; either using
- pre-shared keys or secrets, or more complex schemes that
- involve backend services such as RADIUS. Most users
- will use open authentication which is the default
- setting. Next most common setup is WPA-PSK, also known
- as WPA Personal, which is described <link
- linkend="network-wireless-wpa-wpa-psk">below</link>.</para>
+ common scheme, open authentication, allows any station
+ to join the network and communicate. This is the
+ authentication to use for test purposes the first time
+ a wireless network is setup. Other schemes require
+ cryptographic handshakes to be completed before data
+ traffic can flow, either using pre-shared keys or
+ secrets, or more complex schemes that involve backend
+ services such as <acronym>RADIUS</acronym>. Open
+ authentication is the default setting. The next most
+ common setup is <acronym>WPA-PSK</acronym>, also
+ known as <acronym>WPA</acronym> Personal, which is
+ described in <xref
+ linkend="network-wireless-wpa-wpa-psk"/>.</para>
<note>
- <para>If you have an &apple; &airport; Extreme base
- station for an access point you may need to configure
- shared-key authentication together with a WEP key.
- This can be done in the
- <filename>/etc/rc.conf</filename> file or using the
- &man.wpa.supplicant.8; program. If you have a single
- &airport; base station you can setup access with
- something like:</para>
+ <para>If using an &apple; &airport; Extreme base
+ station for an access point, shared-key authentication
+ together with a <acronym>WEP</acronym> key needs to
+ be configured. This can be configured in
+ <filename>/etc/rc.conf</filename> or by using
+ &man.wpa.supplicant.8;. For a single &airport; base
+ station, access can be configured with:</para>
<programlisting>wlans_ath0="wlan0"
ifconfig_wlan0="authmode shared wepmode on weptxkey <replaceable>1</replaceable> wepkey <replaceable>01234567</replaceable> DHCP"</programlisting>
- <para>In general shared key authentication is to be
- avoided because it uses the WEP key material in a
- highly-constrained manner making it even easier to
- crack the key. If WEP must be used (e.g., for
- compatibility with legacy devices) it is better to use
- WEP with <literal>open</literal> authentication. More
- information regarding WEP can be found in the
- <xref linkend="network-wireless-wep"/>.</para>
+ <para>In general, shared key authentication should be
+ avoided because it uses the <acronym>WEP</acronym> key
+ material in a highly-constrained manner, making it
+ even easier to crack the key. If
+ <acronym>WEP</acronym> must be used for compatibility
+ with legacy devices, it is better to use
+ <acronym>WEP</acronym> with <literal>open</literal>
+ authentication. More information regarding
+ <acronym>WEP</acronym> can be found in <xref
+ linkend="network-wireless-wep"/>.</para>
</note>
</sect5>
<sect5>
- <title>Getting an IP Address with DHCP</title>
-
- <para>Once you have selected an access point and set the
- authentication parameters, you will have to get an IP
- address to communicate. Most of time you will obtain
- your wireless IP address via DHCP. To achieve that,
- edit <filename>/etc/rc.conf</filename> and add
- <literal>DHCP</literal> to the configuration for your
- device as shown in various examples above:</para>
+ <title>Getting an <acronym>IP</acronym> Address with
+ <acronym>DHCP</acronym></title>
+
+ <para>Once an access point is selected and the
+ authentication parameters are set, an
+ <acronym>IP</acronym> address must be obtained in
+ order to communicate. Most of the time, the
+ <acronym>IP</acronym> address is obtained via
+ <acronym>DHCP</acronym>. To achieve that, edit
+ <filename>/etc/rc.conf</filename> and add
+ <literal>DHCP</literal> to the configuration for the
+ device:</para>
<programlisting>wlans_ath0="wlan0"
ifconfig_wlan0="DHCP"</programlisting>
- <para>At this point, you are ready to bring up the
- wireless interface:</para>
+ <para>The
+ wireless interface is now ready to bring up:</para>
<screen>&prompt.root; <userinput>service netif start</userinput></screen>
- <para>Once the interface is running, use
- <command>ifconfig</command> to see the status of the
- interface <devicename>ath0</devicename>:</para>
+ <para>Once the interface is running, use &man.ifconfig.8;
+ to see the status of the interface
+ <devicename>ath0</devicename>:</para>
<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput>
wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
@@ -1174,24 +1150,23 @@ wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
scanvalid 60 bgscan bgscanintvl 300 bgscanidle 250 roam:rssi 7
roam:rate 5 protmode CTS wme burst</screen>
- <para>The <literal>status: associated</literal> means you
- are connected to the wireless network (to the
- <literal>dlinkap</literal> network in our case). The
- <literal>bssid 00:13:46:49:41:76</literal> part is the
- MAC address of your access point; the
- <literal>authmode OPEN</literal> part informs you that
- the communication is not encrypted.</para>
+ <para>The <literal>status: associated</literal> line means
+ that it is connected to the wireless network. The
+ <literal>bssid 00:13:46:49:41:76</literal> is the
+ <acronym>MAC</acronym> address of the access point and
+ <literal>authmode OPEN</literal> indicates that the
+ communication is not encrypted.</para>
</sect5>
<sect5>
- <title>Static IP Address</title>
+ <title>Static <acronym>IP</acronym> Address</title>
- <para>In the case you cannot obtain an IP address from a
- DHCP server, you can set a fixed IP address. Replace
- the <literal>DHCP</literal> keyword shown above with the
+ <para>In an <acronym>IP</acronym> address cannot be
+ obtained from a <acronym>DHCP</acronym> server, set a
+ fixed <acronym>IP</acronym> address. Replace the
+ <literal>DHCP</literal> keyword shown above with the
address information. Be sure to retain any other
- parameters you have set up for selecting an access
- point:</para>
+ parameters for selecting the access point:</para>
<programlisting>wlans_ath0="wlan0"
ifconfig_wlan0="inet <replaceable>192.168.1.100</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>your_ssid_here</replaceable>"</programlisting>
@@ -1199,80 +1174,92 @@ ifconfig_wlan0="inet <replaceable>192.168.1.100</replaceable> netmask <replaceab
</sect4>
<sect4 id="network-wireless-wpa">
- <title>WPA</title>
-
- <para>WPA (Wi-Fi Protected Access) is a security protocol
- used together with 802.11 networks to address the lack of
- proper authentication and the weakness of
- <link linkend="network-wireless-wep">WEP</link>. WPA
- leverages the 802.1X authentication protocol and uses one
- of several ciphers instead of WEP for data integrity. The
- only cipher required by WPA is TKIP (Temporary Key
- Integrity Protocol). TKIP is a cipher that extends the
- basic RC4 cipher used by WEP by adding integrity checking,
- tamper detection, and measures for responding to any
- detected intrusions. TKIP is designed to work on legacy
- hardware with only software modification; it represents a
- compromise that improves security but is still not
- entirely immune to attack. WPA also specifies the
- AES-CCMP cipher as an alternative to TKIP and that is
- preferred when possible; for this specification the term
- WPA2 (or RSN) is commonly used.</para>
-
- <para>WPA defines authentication and encryption protocols.
- Authentication is most commonly done using one of two
- techniques: by 802.1X and a backend authentication service
- such as RADIUS, or by a minimal handshake between the
- station and the access point using a pre-shared secret.
- The former is commonly termed WPA Enterprise with the
- latter known as WPA Personal. Since most people will not
- set up a RADIUS backend server for their wireless network,
- WPA-PSK is by far the most commonly encountered
- configuration for WPA.</para>
-
- <para>The control of the wireless connection and the
- authentication (key negotiation or authentication with a
- server) is done with the &man.wpa.supplicant.8; utility.
- This program requires a configuration file,
+ <title><acronym>WPA</acronym></title>
+
+ <para>Wi-Fi Protected Access (<acronym>WPA</acronym>) is a
+ security protocol used together with 802.11 networks to
+ address the lack of proper authentication and the weakness
+ of <acronym>WEP</acronym>. WPA leverages the 802.1X
+ authentication protocol and uses one of several ciphers
+ instead of <acronym>WEP</acronym> for data integrity.
+ The only cipher required by <acronym>WPA</acronym> is the
+ Temporary Key Integrity Protocol
+ (<acronym>TKIP</acronym>). <acronym>TKIP</acronym> is a
+ cipher that extends the basic RC4 cipher used by
+ <acronym>WEP</acronym> by adding integrity checking,
+ tamper detection, and measures for responding to detected
+ intrusions. <acronym>TKIP</acronym> is designed to work
+ on legacy hardware with only software modification. It
+ represents a compromise that improves security but is
+ still not entirely immune to attack.
+ <acronym>WPA</acronym> also specifies the
+ <acronym>AES-CCMP</acronym> cipher as an alternative to
+ <acronym>TKIP</acronym>, and that is preferred when
+ possible. For this specification, the term
+ <acronym>WPA2</acronym> or <acronym>RSN</acronym> is
+ commonly used.</para>
+
+ <para><acronym>WPA</acronym> defines authentication and
+ encryption protocols. Authentication is most commonly
+ done using one of two techniques: by 802.1X and a backend
+ authentication service such as <acronym>RADIUS</acronym>,
+ or by a minimal handshake between the station and the
+ access point using a pre-shared secret. The former is
+ commonly termed <acronym>WPA</acronym> Enterprise and the
+ latter is known as <acronym>WPA</acronym> Personal. Since
+ most people will not set up a <acronym>RADIUS</acronym>
+ backend server for their wireless network,
+ <acronym>WPA-PSK</acronym> is by far the most commonly
+ encountered configuration for
+ <acronym>WPA</acronym>.</para>
+
+ <para>The control of the wireless connection and the key
+ negotiation or authentication with a server is done using
+ &man.wpa.supplicant.8;. This program requires a
+ configuration file,
<filename>/etc/wpa_supplicant.conf</filename>, to run.
- More information regarding this file can be found in the
- &man.wpa.supplicant.conf.5; manual page.</para>
+ More information regarding this file can be found in
+ &man.wpa.supplicant.conf.5;.</para>
<sect5 id="network-wireless-wpa-wpa-psk">
- <title>WPA-PSK</title>
-
- <para>WPA-PSK, also known as WPA-Personal, is based on a
- pre-shared key (PSK) generated from a given password and
- that will be used as the master key in the wireless
- network. This means every wireless user will share the
- same key. WPA-PSK is intended for small networks where
- the use of an authentication server is not possible or
- desired.</para>
+ <title><acronym>WPA-PSK</acronym></title>
+
+ <para><acronym>WPA-PSK</acronym>, also known as
+ <acronym>WPA</acronym> Personal, is based on a
+ pre-shared key (<acronym>PSK</acronym>) which is
+ generated from a given password and used as the master
+ key in the wireless network. This means every wireless
+ user will share the same key.
+ <acronym>WPA-PSK</acronym> is intended for small
+ networks where the use of an authentication server is
+ not possible or desired.</para>
<warning>
- <para>Always use strong passwords that are
- sufficiently long and made from a rich alphabet so
- they will not be guessed and/or attacked.</para>
+ <para>Always use strong passwords that are sufficiently
+ long and made from a rich alphabet so that they will
+ not be easily guessed or attacked.</para>
</warning>
- <para>The first step is the configuration of the
- <filename>/etc/wpa_supplicant.conf</filename> file with
- the SSID and the pre-shared key of your network:</para>
+ <para>The first step is the configuration of
+ <filename>/etc/wpa_supplicant.conf</filename> with
+ the <acronym>SSID</acronym> and the pre-shared key of
+ the network:</para>
<programlisting>network={
ssid="freebsdap"
psk="freebsdmall"
}</programlisting>
- <para>Then, in <filename>/etc/rc.conf</filename>, we
+ <para>Then, in <filename>/etc/rc.conf</filename>,
indicate that the wireless device configuration will be
- done with WPA and the IP address will be obtained with
- DHCP:</para>
+ done with <acronym>WPA</acronym> and the
+ <acronym>IP</acronym> address will be obtained with
+ <acronym>DHCP</acronym>:</para>
<programlisting>wlans_ath0="wlan0"
ifconfig_wlan0="WPA DHCP"</programlisting>
- <para>Then we can bring up the interface:</para>
+ <para>Then, bring up the interface:</para>
<screen>&prompt.root; <userinput>service netif start</userinput>
Starting wpa_supplicant.
@@ -1293,10 +1280,9 @@ wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS
wme burst roaming MANUAL</screen>
- <para>Or you can try to configure it manually using the
- same <filename>/etc/wpa_supplicant.conf</filename> <link
- linkend="network-wireless-wpa-wpa-psk">above</link>, and
- run:</para>
+ <para>Or, try to configure the interface manually using
+ the information in
+ <filename>/etc/wpa_supplicant.conf</filename>:</para>
<screen>&prompt.root; <userinput>wpa_supplicant -i <replaceable>wlan0</replaceable> -c /etc/wpa_supplicant.conf</userinput>
Trying to associate with 00:11:95:c3:0d:ac (SSID='freebsdap' freq=2412 MHz)
@@ -1304,9 +1290,9 @@ Associated with 00:11:95:c3:0d:ac
WPA: Key negotiation completed with 00:11:95:c3:0d:ac [PTK=CCMP GTK=CCMP]
CTRL-EVENT-CONNECTED - Connection to 00:11:95:c3:0d:ac completed (auth) [id=0 id_str=]</screen>
- <para>The next operation is the launch of the
- <command>dhclient</command> command to get the IP
- address from the DHCP server:</para>
+ <para>The next operation is to launch &man.dhclient.8;
+ to get the <acronym>IP</acronym> address from the
+ <acronym>DHCP</acronym> server:</para>
<screen>&prompt.root; <userinput>dhclient <replaceable>wlan0</replaceable></userinput>
DHCPREQUEST on wlan0 to 255.255.255.255 port 67
@@ -1326,17 +1312,15 @@ wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
<note>
<para>If <filename>/etc/rc.conf</filename> has an
- <literal>ifconfig_wlan0</literal> entry with the
- <literal>DHCP</literal> string (like
- <literal>ifconfig_wlan0="DHCP"</literal>),
- <command>dhclient</command> will be launched
- automatically after <command>wpa_supplicant</command>
- associates with the access point.</para>
+ <literal>ifconfig_wlan0="DHCP"</literal> entry,
+ &man.dhclient.8; will be launched automatically after
+ &man.wpa.supplicant.8; associates with the access
+ point.</para>
</note>
- <para>If DHCP is not possible or desired,
- you can set a static IP address after
- <command>wpa_supplicant</command> has authenticated the
+ <para>If <acronym>DHCP</acronym> is not possible or
+ desired, set a static <acronym>IP</acronym> address
+ after &man.wpa.supplicant.8; has authenticated the
station:</para>
<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.100</replaceable> netmask <replaceable>255.255.255.0</replaceable></userinput>
@@ -1352,43 +1336,51 @@ wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS
wme burst roaming MANUAL</screen>
- <para>When DHCP is not used, you also have to manually set
- the default gateway and the nameserver:</para>
+ <para>When <acronym>DHCP</acronym> is not used, the
+ default gateway and the nameserver also have to be
+ manually set:</para>
<screen>&prompt.root; <userinput>route add default <replaceable>your_default_router</replaceable></userinput>
&prompt.root; <userinput>echo "nameserver <replaceable>your_DNS_server</replaceable>" &gt;&gt; /etc/resolv.conf</userinput></screen>
</sect5>
<sect5 id="network-wireless-wpa-eap-tls">
- <title>WPA with EAP-TLS</title>
-
- <para>The second way to use WPA is with an 802.1X backend
- authentication server. In this case WPA is called
- WPA-Enterprise to differentiate it from the less secure
- WPA-Personal with its pre-shared key.
- Authentication in WPA-Enterprise is based on the
- Extensible Authentication Protocol (EAP).</para>
-
- <para>EAP does not come with an encryption method.
- Instead, it was decided to embed EAP inside an encrypted
- tunnel. There are many EAP authentication methods, but
- EAP-TLS, EAP-TTLS, and EAP-PEAP are the most
+ <title><acronym>WPA</acronym> with
+ <acronym>EAP-TLS</acronym></title>
+
+ <para>The second way to use <acronym>WPA</acronym> is with
+ an 802.1X backend authentication server. In this case,
+ <acronym>WPA</acronym> is called
+ <acronym>WPA</acronym> Enterprise to differentiate it
+ from the less secure <acronym>WPA</acronym> Personal.
+ Authentication in <acronym>WPA</acronym> Enterprise is
+ based on the Extensible Authentication Protocol
+ (<acronym>EAP</acronym>).</para>
+
+ <para><acronym>EAP</acronym> does not come with an
+ encryption method. Instead, <acronym>EAP</acronym> is
+ embedded inside an encrypted tunnel. There are many
+ <acronym>EAP</acronym> authentication methods, but
+ <acronym>EAP-TLS</acronym>, <acronym>EAP-TTLS</acronym>,
+ and <acronym>EAP-PEAP</acronym> are the most
common.</para>
- <para>EAP-TLS (EAP with Transport Layer Security) is a
- very well-supported authentication protocol in the
- wireless world since it was the first EAP method to be
- certified by the <ulink
- url="http://www.wi-fi.org/">Wi-Fi alliance</ulink>.
- EAP-TLS will require three certificates to run: the CA
- certificate (installed on all machines), the server
- certificate for your authentication server, and one
- client certificate for each wireless client. In this
- EAP method, both authentication server and wireless
- client authenticate each other in presenting their
- respective certificates, and they verify that these
- certificates were signed by your organization's
- certificate authority (CA).</para>
+ <para>EAP with Transport Layer Security
+ (<acronym>EAP-TLS</acronym>) is a well-supported
+ wireless authentication protocol since it was the
+ first <acronym>EAP</acronym> method to be certified
+ by the <ulink
+ url="http://www.wi-fi.org/">Wi-Fi alliance</ulink>.
+ <acronym>EAP-TLS</acronym> requires three certificates
+ to run: the certificate of the Certificate Authority
+ (<acronym>CA</acronym>) installed on all machines, the
+ server certificate for the authentication server, and
+ one client certificate for each wireless client. In
+ this <acronym>EAP</acronym> method, both the
+ authentication server and wireless client authenticate
+ each other by presenting their respective certificates,
+ and then verify that these certificates were signed by
+ the organization's <acronym>CA</acronym>.</para>
<para>As previously, the configuration is done via
<filename>/etc/wpa_supplicant.conf</filename>:</para>
@@ -1408,35 +1400,38 @@ wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
<calloutlist>
<callout arearefs="co-tls-ssid">
<para>This field indicates the network name
- (SSID).</para>
+ (<acronym>SSID</acronym>).</para>
</callout>
<callout arearefs="co-tls-proto">
- <para>Here, we use RSN (&ieee; 802.11i) protocol,
- i.e., WPA2.</para>
+ <para>This example uses the <acronym>RSN</acronym>
+ &ieee; 802.11i protocol, also known as
+ <acronym>WPA2</acronym>.</para>
</callout>
<callout arearefs="co-tls-kmgmt">
<para>The <literal>key_mgmt</literal> line refers to
- the key management protocol we use. In our case it
- is WPA using EAP authentication:
- <literal>WPA-EAP</literal>.</para>
+ the key management protocol to use. In this
+ example, it is <acronym>WPA</acronym> using
+ <acronym>EAP</acronym> authentication.</para>
</callout>
<callout arearefs="co-tls-eap">
- <para>In this field, we mention the EAP method for our
- connection.</para>
+ <para>This field indicates the <acronym>EAP</acronym>
+ method for the connection.</para>
</callout>
<callout arearefs="co-tls-id">
<para>The <literal>identity</literal> field contains
- the identity string for EAP.</para>
+ the identity string for
+ <acronym>EAP</acronym>.</para>
</callout>
<callout arearefs="co-tls-cacert">
<para>The <literal>ca_cert</literal> field indicates
- the pathname of the CA certificate file. This file
- is needed to verify the server certificate.</para>
+ the pathname of the <acronym>CA</acronym>
+ certificate file. This file is needed to verify
+ the server certificate.</para>
</callout>
<callout arearefs="co-tls-clientcert">
@@ -1458,7 +1453,7 @@ wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
</callout>
</calloutlist>
- <para>Then add the following lines to
+ <para>Then, add the following lines to
<filename>/etc/rc.conf</filename>:</para>
<programlisting>wlans_ath0="wlan0"
@@ -1483,28 +1478,27 @@ wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS
wme burst roaming MANUAL</screen>
- <para>As previously shown, it is also possible to bring up
- the interface manually with both
- <command>wpa_supplicant</command> and
- <command>ifconfig</command> commands.</para>
+ <para>It is also possible to bring up the interface
+ manually using &man.wpa.supplicant.8; and
+ &man.ifconfig.8;.</para>
</sect5>
<sect5 id="network-wireless-wpa-eap-ttls">
- <title>WPA with EAP-TTLS</title>
-
- <para>With EAP-TLS both the authentication server and the
- client need a certificate, with EAP-TTLS (EAP-Tunneled
- Transport Layer Security) a client certificate is
- optional. This method is close to what some secure web
- sites do , where the web server can create a secure SSL
- tunnel even if the visitors do not have client-side
- certificates. EAP-TTLS will use the encrypted TLS
- tunnel for safe transport of the authentication
- data.</para>
-
- <para>The configuration is done via the
- <filename>/etc/wpa_supplicant.conf</filename>
- file:</para>
+ <title><acronym>WPA</acronym> with
+ <acronym>EAP-TTLS</acronym></title>
+
+ <para>With <acronym>EAP-TTLS</acronym>, both the
+ authentication server and the client need a certificate.
+ With <acronym>EAP-TTLS</acronym>, a client certificate
+ is optional. This method is similar to a web server
+ which creates a secure <acronym>SSL</acronym> tunnel
+ even if visitors do not have client-side certificates.
+ <acronym>EAP-TTLS</acronym> uses an encrypted
+ <acronym>TLS</acronym> tunnel for safe transport of
+ the authentication data.</para>
+
+ <para>The required configuration can be added to
+ <filename>/etc/wpa_supplicant.conf</filename>:</para>
<programlisting>network={
ssid="freebsdap"
@@ -1519,37 +1513,41 @@ wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
<calloutlist>
<callout arearefs="co-ttls-eap">
- <para>In this field, we mention the EAP method for our
- connection.</para>
+ <para>This field specifies the <acronym>EAP</acronym>
+ method for the connection.</para>
</callout>
<callout arearefs="co-ttls-id">
<para>The <literal>identity</literal> field contains
- the identity string for EAP authentication inside
- the encrypted TLS tunnel.</para>
+ the identity string for <acronym>EAP</acronym>
+ authentication inside the encrypted
+ <acronym>TLS</acronym> tunnel.</para>
</callout>
<callout arearefs="co-ttls-passwd">
<para>The <literal>password</literal> field contains
- the passphrase for the EAP authentication.</para>
+ the passphrase for the <acronym>EAP</acronym>
+ authentication.</para>
</callout>
<callout arearefs="co-ttls-cacert">
<para>The <literal>ca_cert</literal> field indicates
- the pathname of the CA certificate file. This file
- is needed to verify the server certificate.</para>
+ the pathname of the <acronym>CA</acronym>
+ certificate file. This file is needed to verify
+ the server certificate.</para>
</callout>
<callout arearefs="co-ttls-pha2">
- <para>In this field, we mention the authentication
- method used in the encrypted TLS tunnel. In our
- case, EAP with MD5-Challenge has been used. The
- <quote>inner authentication</quote> phase is often
- called <quote>phase2</quote>.</para>
+ <para>This field specifies the authentication
+ method used in the encrypted <acronym>TLS</acronym>
+ tunnel. In this example,
+ <acronym>EAP</acronym> with MD5-Challenge is used.
+ The <quote>inner authentication</quote> phase is
+ often called <quote>phase2</quote>.</para>
</callout>
</calloutlist>
- <para>You also have to add the following lines to
+ <para>Next, add the following lines to
<filename>/etc/rc.conf</filename>:</para>
<programlisting>wlans_ath0="wlan0"
@@ -1577,34 +1575,42 @@ wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
</sect5>
<sect5 id="network-wireless-wpa-eap-peap">
- <title>WPA with EAP-PEAP</title>
+ <title><acronym>WPA</acronym> with
+ <acronym>EAP-PEAP</acronym></title>
<note>
- <para>PEAPv0/EAP-MSCHAPv2 is the most common PEAP
- method. In the rest of this document, we will use the
- PEAP term to refer to that method.</para>
+ <para><acronym>PEAPv0/EAP-MSCHAPv2</acronym> is the most
+ common <acronym>PEAP</acronym> method. In this
+ chapter, the term <acronym>PEAP</acronym> is used to
+ refer to that method.</para>
</note>
- <para>PEAP (Protected EAP) has been designed as an
- alternative to EAP-TTLS, and is the most used EAP
- standard after EAP-TLS. In other words, if you have a
- network with mixed OSes, PEAP should be the most
- supported standard after EAP-TLS.</para>
+ <para>Protected EAP (<acronym>PEAP</acronym>) is designed
+ as an alternative to <acronym>EAP-TTLS</acronym> and
+ is the most used <acronym>EAP</acronym> standard after
+ <acronym>EAP-TLS</acronym>. In a network with mixed
+ operating systems, <acronym>PEAP</acronym> should be
+ the most supported standard after
+ <acronym>EAP-TLS</acronym>.</para>
- <para>PEAP is similar to EAP-TTLS: it uses a server-side
+ <para><acronym>PEAP</acronym> is similar to
+ <acronym>EAP-TTLS</acronym> as it uses a server-side
certificate to authenticate clients by creating an
- encrypted TLS tunnel between the client and the
- authentication server, which protects the ensuing
- exchange of authentication information. In terms of
- security, the difference between EAP-TTLS and PEAP is
- that PEAP authentication broadcasts the username in the
- clear, with only the password sent in the encrypted TLS
- tunnel. EAP-TTLS will use the TLS tunnel for both
- username and password.</para>
-
- <para>We have to edit the
- <filename>/etc/wpa_supplicant.conf</filename> file and
- add the EAP-PEAP related settings:</para>
+ encrypted <acronym>TLS</acronym> tunnel between the
+ client and the authentication server, which protects
+ the ensuing exchange of authentication information.
+ <acronym>PEAP</acronym> authentication differs from
+ <acronym>EAP-TTLS</acronym> as it broadcasts the
+ username in the clear and only the password is sent
+ in the encrypted <acronym>TLS</acronym> tunnel.
+ <acronym>EAP-TTLS</acronym> will use the
+ <acronym>TLS</acronym> tunnel for both the username
+ and password.</para>
+
+ <para>Add the following lines to
+ <filename>/etc/wpa_supplicant.conf</filename> to
+ configure the <acronym>EAP-PEAP</acronym> related
+ settings:</para>
<programlisting>network={
ssid="freebsdap"
@@ -1620,54 +1626,58 @@ wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
<calloutlist>
<callout arearefs="co-peap-eap">
- <para>In this field, we mention the EAP method for our
- connection.</para>
+ <para>This field specifies the <acronym>EAP</acronym>
+ method for the connection.</para>
</callout>
<callout arearefs="co-peap-id">
<para>The <literal>identity</literal> field contains
- the identity string for EAP authentication inside
- the encrypted TLS tunnel.</para>
+ the identity string for <acronym>EAP</acronym>
+ authentication inside the encrypted
+ <acronym>TLS</acronym> tunnel.</para>
</callout>
<callout arearefs="co-peap-passwd">
<para>The <literal>password</literal> field contains
- the passphrase for the EAP authentication.</para>
+ the passphrase for the <acronym>EAP</acronym>
+ authentication.</para>
</callout>
<callout arearefs="co-peap-cacert">
<para>The <literal>ca_cert</literal> field indicates
- the pathname of the CA certificate file. This file
- is needed to verify the server certificate.</para>
+ the pathname of the <acronym>CA</acronym>
+ certificate file. This file is needed to verify
+ the server certificate.</para>
</callout>
<callout arearefs="co-peap-pha1">
<para>This field contains the parameters for the
- first phase of authentication (the TLS tunnel).
- According to the authentication server used, you
- will have to specify a specific label for
- authentication. Most of the time, the label will be
- <quote>client EAP encryption</quote> which is set by
- using <literal>peaplabel=0</literal>. More
- information can be found in the
- &man.wpa.supplicant.conf.5; manual page.</para>
+ first phase of authentication, the
+ <acronym>TLS</acronym> tunnel. According to the
+ authentication server used, specify a specific
+ label for authentication. Most of the time, the
+ label will be <quote>client <acronym>EAP</acronym>
+ encryption</quote> which is set by using
+ <literal>peaplabel=0</literal>. More information
+ can be found in &man.wpa.supplicant.conf.5;.</para>
</callout>
<callout arearefs="co-peap-pha2">
- <para>In this field, we mention the authentication
- protocol used in the encrypted TLS tunnel. In the
- case of PEAP, it is
+ <para>This field specifies the authentication
+ protocol used in the encrypted
+ <acronym>TLS</acronym> tunnel. In the
+ case of <acronym>PEAP</acronym>, it is
<literal>auth=MSCHAPV2</literal>.</para>
</callout>
</calloutlist>
- <para>The following must be added to
+ <para>Add the following to
<filename>/etc/rc.conf</filename>:</para>
<programlisting>wlans_ath0="wlan0"
ifconfig_wlan0="WPA DHCP"</programlisting>
- <para>Then we can bring up the interface:</para>
+ <para>Then, bring up the interface:</para>
<screen>&prompt.root; <userinput>service netif start</userinput>
Starting wpa_supplicant.
@@ -1690,15 +1700,15 @@ wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
</sect4>
<sect4 id="network-wireless-wep">
- <title>WEP</title>
+ <title><acronym>WEP</acronym></title>
- <para>WEP (Wired Equivalent Privacy) is part of the original
- 802.11 standard. There is no authentication mechanism,
- only a weak form of access control, and it is easily
- cracked.</para>
+ <para>Wired Equivalent Privacy (<acronym>WEP</acronym>) is
+ part of the original 802.11 standard. There is no
+ authentication mechanism, only a weak form of access
+ control which is easily cracked.</para>
- <para>WEP can be set up with
- <command>ifconfig</command>:</para>
+ <para><acronym>WEP</acronym> can be set up using
+ &man.ifconfig.8;:</para>
<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput>
&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.1.100</replaceable> netmask <replaceable>255.255.255.0</replaceable> \
@@ -1707,38 +1717,38 @@ wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
<itemizedlist>
<listitem>
- <para>The <literal>weptxkey</literal> means which WEP
- key will be used in the transmission. Here we used
- the third key. This must match the setting in the
- access point. If you do not have any idea of which
- key is used by the access point, try
- <literal>1</literal> (i.e., the first key) for this
+ <para>The <literal>weptxkey</literal> specifies which
+ <acronym>WEP</acronym> key will be used in the
+ transmission. This example uses the third key.
+ This must match the setting on the access point.
+ When unsure which key is used by the access point,
+ try <literal>1</literal> (the first key) for this
value.</para>
</listitem>
<listitem>
<para>The <literal>wepkey</literal> selects one of the
- WEP keys. It should be in the format
- <replaceable>index:key</replaceable>. Key
+ <acronym>WEP</acronym> keys. It should be in the
+ format <replaceable>index:key</replaceable>. Key
<literal>1</literal> is used by default; the index
- only needs to be set if we use a key other
- than the first key.</para>
+ only needs to be set when using a key other than the
+ first key.</para>
<note>
- <para>You must replace the
- <literal>0x3456789012</literal> with the key
- configured for use on the access point.</para>
+ <para>Replace the <literal>0x3456789012</literal>
+ with the key configured for use on the access
+ point.</para>
</note>
</listitem>
</itemizedlist>
- <para>You are encouraged to read the &man.ifconfig.8; manual
- page for further information.</para>
+ <para>Refer to &man.ifconfig.8; for further
+ information.</para>
- <para>The <command>wpa_supplicant</command> facility also
- can be used to configure your wireless interface with WEP.
- The example above can be set up by adding the following
- lines to
+ <para>The &man.wpa.supplicant.8; facility can be used to
+ configure a wireless interface with
+ <acronym>WEP</acronym>. The example above can be set up
+ by adding the following lines to
<filename>/etc/wpa_supplicant.conf</filename>:</para>
<programlisting>network={
@@ -1760,13 +1770,14 @@ Associated with 00:13:46:49:41:76</screen>
<sect2>
<title>Ad-hoc Mode</title>
- <para>IBSS mode, also called ad-hoc mode, is designed for point
- to point connections. For example, to establish an ad-hoc
- network between the machine <hostid>A</hostid> and the machine
- <hostid>B</hostid>, we will just need to choose two IP
- addresses and a SSID.</para>
+ <para><acronym>IBSS</acronym> mode, also called ad-hoc mode, is
+ designed for point to point connections. For example, to
+ establish an ad-hoc network between the machines
+ <hostid>A</hostid> and <hostid>B</hostid>, choose two
+ <acronym>IP</acronym> addresses and a
+ <acronym>SSID</acronym>.</para>
- <para>On the box <hostid>A</hostid>:</para>
+ <para>On <hostid>A</hostid>:</para>
<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable> wlanmode adhoc</userinput>
&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.1</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable></userinput>
@@ -1780,10 +1791,10 @@ Associated with 00:13:46:49:41:76</screen>
country US ecm authmode OPEN privacy OFF txpower 21.5 scanvalid 60
protmode CTS wme burst</screen>
- <para>The <literal>adhoc</literal> parameter indicates the
- interface is running in the IBSS mode.</para>
+ <para>The <literal>adhoc</literal> parameter indicates that the
+ interface is running in <acronym>IBSS</acronym> mode.</para>
- <para>On <hostid>B</hostid>, we should be able to detect
+ <para><hostid>B</hostid> should now be able to detect
<hostid>A</hostid>:</para>
<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable> wlanmode adhoc</userinput>
@@ -1791,9 +1802,9 @@ Associated with 00:13:46:49:41:76</screen>
SSID/MESH ID BSSID CHAN RATE S:N INT CAPS
freebsdap 02:11:95:c3:0d:ac 2 54M -64:-96 100 IS WME</screen>
- <para>The <literal>I</literal> in the output confirms the
- machine <hostid>A</hostid> is in ad-hoc mode. We just have to
- configure <hostid>B</hostid> with a different IP
+ <para>The <literal>I</literal> in the output confirms that
+ <hostid>A</hostid> is in ad-hoc mode. Now, configure
+ <hostid>B</hostid> with a different <acronym>IP</acronym>
address:</para>
<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.2</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable></userinput>
@@ -1814,42 +1825,46 @@ Associated with 00:13:46:49:41:76</screen>
<sect2 id="network-wireless-ap">
<title>&os; Host Access Points</title>
- <para>&os; can act as an Access Point (AP) which eliminates the
- need to buy a hardware AP or run an ad-hoc network. This can
- be particularly useful when your &os; machine is acting as a
- gateway to another network (e.g., the Internet).</para>
+ <para>&os; can act as an Access Point (<acronym>AP</acronym>)
+ which eliminates the need to buy a hardware
+ <acronym>AP</acronym> or run an ad-hoc network. This can
+ be particularly useful when a &os; machine is acting as a
+ gateway to another network such as the Internet.</para>
<sect3 id="network-wireless-ap-basic">
<title>Basic Settings</title>
- <para>Before configuring your &os; machine as an AP, the
- kernel must be configured with the appropriate wireless
- networking support for your wireless card. You also have to
- add support for the security protocols you intend to
- use. For more details, see
- <xref linkend="network-wireless-basic"/>.</para>
+ <para>Before configuring a &os; machine as an
+ <acronym>AP</acronym>, the kernel must be configured with
+ the appropriate networking support for the wireless card
+ as well as the security protocols being used. For more
+ details, see <xref
+ linkend="network-wireless-basic"/>.</para>
<note>
- <para>The use of the NDIS driver wrapper and the &windows;
- drivers do not currently allow AP operation. Only native
- &os; wireless drivers support AP mode.</para>
+ <para>The <acronym>NDIS</acronym> driver wrapper for
+ &windows; drivers does not currently support
+ <acronym>AP</acronym> operation. Only native &os;
+ wireless drivers support <acronym>AP</acronym>
+ mode.</para>
</note>
- <para>Once wireless networking support is loaded, you can
- check if your wireless device supports the host-based access
- point mode (also known as hostap mode):</para>
+ <para>Once wireless networking support is loaded, check if
+ the wireless device supports the host-based access point
+ mode, also known as hostap mode:</para>
<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput>
&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> list caps</userinput>
drivercaps=6f85edc1&lt;STA,FF,TURBOP,IBSS,HOSTAP,AHDEMO,TXPMGT,SHSLOT,SHPREAMBLE,MONITOR,MBSS,WPA1,WPA2,BURST,WME,WDS,BGSCAN,TXFRAG&gt;
cryptocaps=1f&lt;WEP,TKIP,AES,AES_CCM,TKIPMIC&gt;</screen>
- <para>This output displays the card capabilities; the
- <literal>HOSTAP</literal> word confirms this wireless card
- can act as an Access Point. Various supported ciphers are
- also mentioned: WEP, TKIP, AES, etc. This information
- is important to know what security protocols can be used
- on the Access Point.</para>
+ <para>This output displays the card's capabilities. The
+ <literal>HOSTAP</literal> word confirms that this wireless
+ card can act as an <acronym>AP</acronym>. Various supported
+ ciphers are also listed: <acronym>WEP</acronym>,
+ <acronym>TKIP</acronym>, and <acronym>AES</acronym>. This
+ information indicates which security protocols can be used
+ on the <acronym>AP</acronym>.</para>
<para>The wireless device can only be put into hostap mode
during the creation of the network pseudo-device, so a
@@ -1863,8 +1878,8 @@ cryptocaps=1f&lt;WEP,TKIP,AES,AES_CCM,TKIPMIC&gt;</screen>
<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable> wlanmode hostap</userinput>
&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.1</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable> mode 11g channel 1</userinput></screen>
- <para>Use <command>ifconfig</command> again to see the status
- of the <devicename>wlan0</devicename> interface:</para>
+ <para>Use &man.ifconfig.8; again to see the status of the
+ <devicename>wlan0</devicename> interface:</para>
<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput>
wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
@@ -1893,22 +1908,23 @@ ifconfig_wlan0="inet <replaceable>192.168.0.1</replaceable> netmask <replaceable
<title>Host-based Access Point Without Authentication or
Encryption</title>
- <para>Although it is not recommended to run an AP without any
- authentication or encryption, this is a simple way to check
- if your AP is working. This configuration is also important
- for debugging client issues.</para>
+ <para>Although it is not recommended to run an
+ <acronym>AP</acronym> without any authentication or
+ encryption, this is a simple way to check if the
+ <acronym>AP</acronym> is working. This configuration is
+ also important for debugging client issues.</para>
- <para>Once the AP configured as previously shown, it is
- possible from another wireless machine to initiate a scan to
- find the AP:</para>
+ <para>Once the <acronym>AP</acronym> is configured, initiate
+ a scan from another wireless machine to find the
+ <acronym>AP</acronym>:</para>
<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput>
&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> up scan</userinput>
SSID/MESH ID BSSID CHAN RATE S:N INT CAPS
freebsdap 00:11:95:c3:0d:ac 1 54M -66:-96 100 ES WME</screen>
- <para>The client machine found the Access Point and can be
- associated with it:</para>
+ <para>The client machine found the <acronym>AP</acronym> and
+ can be associated with it:</para>
<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.2</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable></userinput>
&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput>
@@ -1924,39 +1940,42 @@ freebsdap 00:11:95:c3:0d:ac 1 54M -66:-96 100 ES WME</screen>
</sect3>
<sect3>
- <title>WPA Host-based Access Point</title>
-
- <para>This section will focus on setting up &os; Access Point
- using the WPA security protocol. More details regarding WPA
- and the configuration of WPA-based wireless clients can be
- found in the <xref linkend="network-wireless-wpa"/>.</para>
-
- <para>The <application>hostapd</application> daemon is used to
- deal with client authentication and keys management on the
- WPA enabled Access Point.</para>
-
- <para>In the following, all the configuration operations will
- be performed on the &os; machine acting as AP. Once the
- AP is correctly working, <application>hostapd</application>
- should be automatically enabled at boot with the following
- line in <filename>/etc/rc.conf</filename>:</para>
+ <title><acronym>WPA</acronym> Host-based Access Point</title>
+
+ <para>This section focuses on setting up a &os;
+ <acronym>AP</acronym> using the <acronym>WPA</acronym>
+ security protocol. More details regarding
+ <acronym>WPA</acronym> and the configuration of
+ <acronym>WPA</acronym>-based
+ wireless clients can be found in <xref
+ linkend="network-wireless-wpa"/>.</para>
+
+ <para>The &man.hostapd.8; daemon is used to deal with client
+ authentication and key management on the
+ <acronym>WPA</acronym>-enabled <acronym>AP</acronym>.</para>
+
+ <para>The following configuration operations are performed
+ on the &os; machine acting as the <acronym>AP</acronym>.
+ Once the <acronym>AP</acronym> is correctly working,
+ &man.hostapd.8; should be automatically enabled at boot
+ with the following line in
+ <filename>/etc/rc.conf</filename>:</para>
<programlisting>hostapd_enable="YES"</programlisting>
- <para>Before trying to configure
- <application>hostapd</application>, be sure you have done
- the basic settings introduced in the
- <xref linkend="network-wireless-ap-basic"/>.</para>
+ <para>Before trying to configure &man.hostapd.8;, first
+ configure the basic settings introduced in <xref
+ linkend="network-wireless-ap-basic"/>.</para>
<sect4>
- <title>WPA-PSK</title>
+ <title><acronym>WPA-PSK</acronym></title>
- <para>WPA-PSK is intended for small networks where the use
- of an backend authentication server is not possible or
- desired.</para>
+ <para><acronym>WPA-PSK</acronym> is intended for small
+ networks where the use of a backend authentication server
+ is not possible or desired.</para>
- <para>The configuration is done in the
- <filename>/etc/hostapd.conf</filename> file:</para>
+ <para>The configuration is done in
+ <filename>/etc/hostapd.conf</filename>:</para>
<programlisting>interface=wlan0 <co id="co-ap-wpapsk-iface"/>
debug=1 <co id="co-ap-wpapsk-dbug"/>
@@ -1971,30 +1990,28 @@ wpa_pairwise=CCMP TKIP <co id="co-ap-wpapsk-pwise"/></programlisting>
<calloutlist>
<callout arearefs="co-ap-wpapsk-iface">
<para>This field indicates the wireless interface used
- for the Access Point.</para>
+ for the <acronym>AP</acronym>.</para>
</callout>
<callout arearefs="co-ap-wpapsk-dbug">
<para>This field sets the level of verbosity during the
- execution of <application>hostapd</application>. A
- value of <literal>1</literal> represents the minimal
+ execution of &man.hostapd.8;. A value of
+ <literal>1</literal> represents the minimal
level.</para>
</callout>
<callout arearefs="co-ap-wpapsk-ciface">
<para>The <literal>ctrl_interface</literal> field gives
- the pathname of the directory used by
- <application>hostapd</application> to stores its
- domain socket files for the communication with
- external programs such as &man.hostapd.cli.8;. The
- default value is used here.</para>
+ the pathname of the directory used by &man.hostapd.8;
+ to store its domain socket files for the communication
+ with external programs such as &man.hostapd.cli.8;.
+ The default value is used in this example.</para>
</callout>
<callout arearefs="co-ap-wpapsk-cifacegrp">
<para>The <literal>ctrl_interface_group</literal> line
- sets the group (here, it is the
- <groupname>wheel</groupname> group) allowed to access
- to the control interface files.</para>
+ sets the group which is allowed to access the control
+ interface files.</para>
</callout>
<callout arearefs="co-ap-wpapsk-ssid">
@@ -2002,43 +2019,49 @@ wpa_pairwise=CCMP TKIP <co id="co-ap-wpapsk-pwise"/></programlisting>
</callout>
<callout arearefs="co-ap-wpapsk-wpa">
- <para>The <literal>wpa</literal> field enables WPA and
- specifies which WPA authentication protocol will be
- required. A value of <literal>1</literal> configures
- the AP for WPA-PSK.</para>
+ <para>The <literal>wpa</literal> field enables
+ <acronym>WPA</acronym> and specifies which
+ <acronym>WPA</acronym> authentication protocol will
+ be required. A value of <literal>1</literal>
+ configures the <acronym>AP</acronym> for
+ <acronym>WPA-PSK</acronym>.</para>
</callout>
<callout arearefs="co-ap-wpapsk-pass">
<para>The <literal>wpa_passphrase</literal> field
- contains the ASCII passphrase for the WPA
- authentication.</para>
+ contains the ASCII passphrase for
+ <acronym>WPA</acronym> authentication.</para>
<warning>
<para>Always use strong passwords that are
sufficiently long and made from a rich alphabet so
- they will not be guessed and/or attacked.</para>
+ that they will not be easily guessed or
+ attacked.</para>
</warning>
</callout>
<callout arearefs="co-ap-wpapsk-kmgmt">
- <para>The <literal>wpa_key_mgmt</literal> line refers to
- the key management protocol we use. In our case it is
- WPA-PSK.</para>
+ <para>The <literal>wpa_key_mgmt</literal> line refers
+ to the key management protocol to use. This example
+ sets <acronym>WPA-PSK</acronym>.</para>
</callout>
<callout arearefs="co-ap-wpapsk-pwise">
<para>The <literal>wpa_pairwise</literal> field
indicates the set of accepted encryption algorithms by
- the Access Point. Here both TKIP (WPA) and CCMP
- (WPA2) ciphers are accepted. CCMP cipher is an
- alternative to TKIP and that is strongly preferred
- when possible; TKIP should be used solely for stations
- incapable of doing CCMP.</para>
+ the <acronym>AP</acronym>. In this example, both
+ <acronym>TKIP</acronym> (<acronym>WPA</acronym>) and
+ <acronym>CCMP</acronym> (<acronym>WPA2</acronym>)
+ ciphers are accepted. The <acronym>CCMP</acronym>
+ cipher is an alternative to <acronym>TKIP</acronym>
+ and is strongly preferred when possible.
+ <acronym>TKIP</acronym> should be used solely for
+ stations incapable of doing
+ <acronym>CCMP</acronym>.</para>
</callout>
</calloutlist>
- <para>The next step is to start
- <application>hostapd</application>:</para>
+ <para>The next step is to start &man.hostapd.8;:</para>
<screen>&prompt.root; <userinput>service hostapd forcestart</userinput></screen>
@@ -2052,28 +2075,30 @@ wpa_pairwise=CCMP TKIP <co id="co-ap-wpapsk-pwise"/></programlisting>
ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac
authmode WPA2/802.11i privacy MIXED deftxkey 2 TKIP 2:128-bit txpowmax 36 protmode CTS dtimperiod 1 bintval 100</screen>
- <para>The Access Point is running, the clients can now be
- associated with it, see
- <xref linkend="network-wireless-wpa"/> for more details.
- It is possible to see the stations associated with the AP
- using the <command>ifconfig
- <replaceable>wlan0</replaceable> list sta</command>
- command.</para>
+ <para>Once the <acronym>AP</acronym> is running, the
+ clients can associate with it. See <xref
+ linkend="network-wireless-wpa"/> for more details.
+ It is possible to see the stations associated with the
+ <acronym>AP</acronym> using <command>ifconfig
+ <replaceable>wlan0</replaceable> list
+ sta</command>.</para>
</sect4>
</sect3>
<sect3>
- <title>WEP Host-based Access Point</title>
+ <title><acronym>WEP</acronym> Host-based Access Point</title>
- <para>It is not recommended to use WEP for setting up an
- Access Point since there is no authentication mechanism and
- it is easily to be cracked. Some legacy wireless cards only
- support WEP as security protocol, these cards will only
- allow to set up AP without authentication or encryption or
- using the WEP protocol.</para>
+ <para>It is not recommended to use <acronym>WEP</acronym> for
+ setting up an <acronym>AP</acronym> since there is no
+ authentication mechanism and the encryption is easily
+ cracked. Some legacy wireless cards only support
+ <acronym>WEP</acronym> and these cards will only support
+ an <acronym>AP</acronym> without authentication or
+ encryption.</para>
<para>The wireless device can now be put into hostap mode and
- configured with the correct SSID and IP address:</para>
+ configured with the correct <acronym>SSID</acronym> and
+ <acronym>IP</acronym> address:</para>
<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable> wlanmode hostap</userinput>
&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.1</replaceable> netmask <replaceable>255.255.255.0</replaceable> \
@@ -2081,25 +2106,26 @@ wpa_pairwise=CCMP TKIP <co id="co-ap-wpapsk-pwise"/></programlisting>
<itemizedlist>
<listitem>
- <para>The <literal>weptxkey</literal> means which WEP
- key will be used in the transmission. Here we used the
- third key (note that the key numbering starts with
- <literal>1</literal>). This parameter must be specified
- to really encrypt the data.</para>
+ <para>The <literal>weptxkey</literal> indicates which
+ <acronym>WEP</acronym> key will be used in the
+ transmission. This example uses the third key as key
+ numbering starts with <literal>1</literal>. This
+ parameter must be specified in order to encrypt the
+ data.</para>
</listitem>
<listitem>
- <para>The <literal>wepkey</literal> means setting the
- selected WEP key. It should in the format
- <replaceable>index:key</replaceable>, if the index is
- not given, key <literal>1</literal> is set. That is
- to say we need to set the index if we use keys other
- than the first key.</para>
+ <para>The <literal>wepkey</literal> sets the selected
+ <acronym>WEP</acronym> key. It should be in the format
+ <replaceable>index:key</replaceable>. If the index is
+ not given, key <literal>1</literal> is set. The index
+ needs to be set when using keys other than the first
+ key.</para>
</listitem>
</itemizedlist>
- <para>Use again <command>ifconfig</command> to see the status
- of the <devicename>wlan0</devicename> interface:</para>
+ <para>Use &man.ifconfig.8; to see the status of the
+ <devicename>wlan0</devicename> interface:</para>
<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput>
wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
@@ -2111,108 +2137,108 @@ wpa_pairwise=CCMP TKIP <co id="co-ap-wpapsk-pwise"/></programlisting>
country US ecm authmode OPEN privacy ON deftxkey 3 wepkey 3:40-bit
txpower 21.5 scanvalid 60 protmode CTS wme burst dtimperiod 1 -dfs</screen>
- <para>From another wireless machine, it is possible to
- initiate a scan to find the AP:</para>
+ <para>From another wireless machine, it is now possible to
+ initiate a scan to find the <acronym>AP</acronym>:</para>
<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput>
&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> up scan</userinput>
SSID BSSID CHAN RATE S:N INT CAPS
freebsdap 00:11:95:c3:0d:ac 1 54M 22:1 100 EPS</screen>
- <para>The client machine found the Access Point and can be
- associated with it using the correct parameters (key, etc.),
- see <xref linkend="network-wireless-wep"/> for more
- details.</para>
+ <para>In this example, the client machine found the
+ <acronym>AP</acronym> and can associate with it using the
+ correct parameters. See <xref
+ linkend="network-wireless-wep"/> for more details.</para>
</sect3>
</sect2>
<sect2>
- <title>Using Both Wired and Wireless Connection</title>
+ <title>Using Both Wired and Wireless Connections</title>
- <para>Wired connection provides better performance and
- reliability, while wireless connection provides flexibility
- and mobility, users of laptop computers usually want to
- combine these together and roam seamlessly between the
- two.</para>
+ <para>A wired connection provides better performance and
+ reliability, while a wireless connection provides flexibility
+ and mobility. Laptop users typically want to roam seamlessly
+ between the two types of connections.</para>
<para>On &os;, it is possible to combine two or even more
network interfaces together in a <quote>failover</quote>
- fashion, that is, to use the most preferred and available
- connection from a group of network interfaces, and have the
- operating system switch automatically when the link state
- changes.</para>
-
- <para>We will cover link aggregation and failover in
- <xref linkend="network-aggregation"/> where an example for
- using both wired and wireless connection is also provided at
- <xref linkend="networking-lagg-wired-and-wireless"/>.</para>
+ fashion. This type of configuration uses the most preferred
+ and available connection from a group of network interfaces,
+ and the operating system switches automatically when the link
+ state changes.</para>
+
+ <para>Link aggregation and failover is covered in <xref
+ linkend="network-aggregation"/> and an example for using
+ both wired and wireless connections is provided at <xref
+ linkend="networking-lagg-wired-and-wireless"/>.</para>
</sect2>
<sect2>
<title>Troubleshooting</title>
- <para>If you are having trouble with wireless networking, there
- are a number of steps you can take to help troubleshoot the
- problem.</para>
+ <para>This section describes
+ a number of steps to help troubleshoot common wireless
+ networking problems.</para>
<itemizedlist>
<listitem>
- <para>If you do not see the access point listed when
- scanning be sure you have not configured your wireless
+ <para>If the access point is not listed when scanning,
+ check that the configuration has not limited the wireless
device to a limited set of channels.</para>
</listitem>
<listitem>
- <para>If you cannot associate to an access point verify the
- configuration of your station matches the one of the
+ <para>If the device cannot associate with an access point,
+ verify that the configuration matches the settings on the
access point. This includes the authentication scheme and
- any security protocols. Simplify your configuration as
- much as possible. If you are using a security protocol
- such as WPA or WEP configure the access point for open
- authentication and no security to see if you can get
- traffic to pass.</para>
+ any security protocols. Simplify the configuration as
+ much as possible. If using a security protocol such as
+ <acronym>WPA</acronym> or <acronym>WEP</acronym>,
+ configure the access point for open authentication and
+ no security to see if traffic will pass.</para>
</listitem>
<listitem>
- <para>Once you can associate to the access point diagnose
- any security configuration using simple tools like
+ <para>Once the system can associate with the access point,
+ diagnose the security configuration using tools like
&man.ping.8;.</para>
- <para>The <command>wpa_supplicant</command> has much
- debugging support; try running it manually with the
- <option>-dd</option> option and look at the system
- logs.</para>
+ <para>Debugging support is provided by
+ &man.wpa.supplicant.8;. Try running this utility manually
+ with the <option>-dd</option> option and look at the
+ system logs.</para>
</listitem>
<listitem>
- <para>There are also many lower-level debugging tools. You
- can enable debugging messages in the 802.11 protocol
- support layer using the <command>wlandebug</command>
- program found in
- <filename class="directory">/usr/src/tools/tools/net80211</filename>.
- For example:</para>
+ <para>There are many lower-level debugging tools.
+ Debugging messages can be enabled in the 802.11 protocol
+ support layer using &man.wlandebug.8;. On a &os; system
+ prior to &os;&nbsp;9.1, this program can be found in
+ <filename
+ class="directory">/usr/src/tools/tools/net80211</filename>.
+ For example, to enable console messages related to
+ scanning for access points and the 802.11 protocol
+ handshakes required to arrange communication:</para>
<screen>&prompt.root; <userinput>wlandebug -i <replaceable>ath0</replaceable> +scan+auth+debug+assoc</userinput>
net.wlan.0.debug: 0 =&gt; 0xc80000&lt;assoc,auth,scan&gt;</screen>
- <para>can be used to enable console messages related to
- scanning for access points and doing the 802.11 protocol
- handshakes required to arrange communication.</para>
-
- <para>There are also many useful statistics maintained by
- the 802.11 layer; the <command>wlanstats</command> tool
+ <para>Many useful statistics are maintained by
+ the 802.11 layer and <command>wlanstats</command>, found
+ in <filename
+ class="directory">/usr/src/tools/tools/net80211</filename>,
will dump this information. These statistics should
- identify all errors identified by the 802.11 layer.
- Beware however that some errors are identified in the
- device drivers that lie below the 802.11 layer so they may
- not show up. To diagnose device-specific problems you
- need to refer to the drivers' documentation.</para>
+ display all errors identified by the 802.11 layer.
+ However, some errors are identified in the device drivers
+ that lie below the 802.11 layer so they may not show up.
+ To diagnose device-specific problems, refer to the
+ drivers' documentation.</para>
</listitem>
</itemizedlist>
<para>If the above information does not help to clarify the
- problem, please submit a problem report and include output
- from the above tools.</para>
+ problem, submit a problem report and include output from the
+ above tools.</para>
</sect2>
</sect1>
@@ -2240,29 +2266,29 @@ freebsdap 00:11:95:c3:0d:ac 1 54M 22:1 100 EPS</screen>
networks operating in the 2.4 GHz unlicensed band, with a
range of 10 meters. Networks are usually formed ad-hoc from
portable devices such as cellular phones, handhelds and
- laptops. Unlike the other popular wireless technology, Wi-Fi,
- Bluetooth offers higher level service profiles, e.g., FTP-like
- file servers, file pushing, voice transport, serial line
- emulation, and more.</para>
+ laptops. Unlike Wi-Fi wireless technology, Bluetooth offers
+ higher level service profiles, such as FTP-like file servers,
+ file pushing, voice transport, serial line emulation, and
+ more.</para>
<para>The Bluetooth stack in &os; is implemented using the
- Netgraph framework (see &man.netgraph.4;). A broad variety of
- Bluetooth USB dongles is supported by the &man.ng.ubt.4;
- driver. The Broadcom BCM2033 chip based Bluetooth devices are
- supported via the &man.ubtbcmfw.4; and &man.ng.ubt.4; drivers.
- The 3Com Bluetooth PC Card 3CRWB60-A is supported by the
+ &man.netgraph.4; framework. A broad variety of Bluetooth
+ <acronym>USB</acronym> dongles is supported by &man.ng.ubt.4;.
+ Broadcom BCM2033 based Bluetooth devices are supported by
+ the &man.ubtbcmfw.4; and &man.ng.ubt.4; drivers. The 3Com
+ Bluetooth PC Card 3CRWB60-A is supported by the
&man.ng.bt3c.4; driver. Serial and UART based Bluetooth
- devices are supported via &man.sio.4;, &man.ng.h4.4; and
- &man.hcseriald.8;. This section describes the use of the USB
- Bluetooth dongle.</para>
+ devices are supported by &man.sio.4;, &man.ng.h4.4; and
+ &man.hcseriald.8;. This section describes the use of a
+ <acronym>USB</acronym> Bluetooth dongle.</para>
</sect2>
<sect2>
<title>Plugging in the Device</title>
- <para>By default Bluetooth device drivers are available as
- kernel modules. Before attaching a device, you will need to
- load the driver into the kernel:</para>
+ <para>By default, Bluetooth device drivers are available as
+ kernel modules. Before attaching a device, load the driver
+ into the kernel:</para>
<screen>&prompt.root; <userinput>kldload ng_ubt</userinput></screen>
@@ -2272,19 +2298,19 @@ freebsdap 00:11:95:c3:0d:ac 1 54M 22:1 100 EPS</screen>
<programlisting>ng_ubt_load="YES"</programlisting>
- <para>Plug in your USB dongle. The output similar to the
- following will appear on the console (or in syslog):</para>
+ <para>Plug in the <acronym>USB</acronym> dongle. Output
+ similar to the following will appear on the console and in
+ the system log:</para>
<screen>ubt0: vendor 0x0a12 product 0x0001, rev 1.10/5.25, addr 2
ubt0: Interface 0 endpoints: interrupt=0x81, bulk-in=0x82, bulk-out=0x2
ubt0: Interface 1 (alt.config 5) endpoints: isoc-in=0x83, isoc-out=0x3,
wMaxPacketSize=49, nframes=6, buffer size=294</screen>
- <para>&man.service.8;
- is used to start and stop the Bluetooth stack. It is a good
- idea to stop the stack before unplugging the device, but it is
- not (usually) fatal. When starting the stack, you will
- receive output similar to the following:</para>
+ <para>To start and stop the Bluetooth stack, use
+ &man.service.8;. It is a good idea to stop the stack before
+ unplugging the device. When starting the stack, the output
+ should be similar to the following:</para>
<screen>&prompt.root; <userinput>service bluetooth start ubt0</userinput>
BD_ADDR: 00:02:72:00:d4:1a
@@ -2301,38 +2327,42 @@ Number of SCO packets: 8</screen>
</sect2>
<sect2>
- <title>Host Controller Interface (HCI)</title>
+ <title>Host Controller Interface
+ (<acronym>HCI</acronym>)</title>
<indexterm><primary>HCI</primary></indexterm>
- <para>Host Controller Interface (HCI) provides a command
- interface to the baseband controller and link manager, and
- access to hardware status and control registers. This
- interface provides a uniform method of accessing the Bluetooth
- baseband capabilities. HCI layer on the Host exchanges data
- and commands with the HCI firmware on the Bluetooth hardware.
- The Host Controller Transport Layer (i.e., physical bus)
- driver provides both HCI layers with the ability to exchange
- information with each other.</para>
-
- <para>A single Netgraph node of type <emphasis>hci</emphasis> is
- created for a single Bluetooth device. The HCI node is
- normally connected to the Bluetooth device driver node
- (downstream) and the L2CAP node (upstream). All HCI
- operations must be performed on the HCI node and not on the
- device driver node. Default name for the HCI node is
- <quote>devicehci</quote>. For more details refer to the
- &man.ng.hci.4; manual page.</para>
+ <para>The Host Controller Interface (<acronym>HCI</acronym>)
+ provides a command interface to the baseband controller and
+ link manager as well as access to hardware status and control
+ registers. This interface provides a uniform method for
+ accessing Bluetooth baseband capabilities. The
+ <acronym>HCI</acronym> layer on the host exchanges data and
+ commands with the <acronym>HCI</acronym> firmware on the
+ Bluetooth hardware. The Host Controller Transport Layer
+ (physical bus) driver provides both <acronym>HCI</acronym>
+ layers with the ability to exchange information.</para>
+
+ <para>A single netgraph node of type <emphasis>hci</emphasis>
+ is created for a single Bluetooth device. The
+ <acronym>HCI</acronym> node is normally connected to the
+ downstream Bluetooth device driver node and the upstream
+ <acronym>L2CAP</acronym> node. All <acronym>HCI</acronym>
+ operations must be performed on the <acronym>HCI</acronym>
+ node and not on the device driver node. The default name
+ for the <acronym>HCI</acronym> node is
+ <quote>devicehci</quote>. For more details, refer to
+ &man.ng.hci.4;.</para>
<para>One of the most common tasks is discovery of Bluetooth
- devices in RF proximity. This operation is called
- <emphasis>inquiry</emphasis>. Inquiry and other HCI related
- operations are done with the &man.hccontrol.8; utility. The
- example below shows how to find out which Bluetooth devices
- are in range. You should receive the list of devices in a few
- seconds. Note that a remote device will only answer the
- inquiry if it put into <emphasis>discoverable</emphasis>
- mode.</para>
+ devices in <acronym>RF</acronym> proximity. This operation is
+ called <emphasis>inquiry</emphasis>. Inquiry and other
+ <acronym>HCI</acronym> related operations are done using
+ &man.hccontrol.8;. The example below shows how to find out
+ which Bluetooth devices are in range. The list of devices
+ should be displayed in a few seconds. Note that a remote
+ device will only answer the inquiry if it is set to
+ <emphasis>discoverable</emphasis> mode.</para>
<screen>&prompt.user; <userinput>hccontrol -n ubt0hci inquiry</userinput>
Inquiry result, num_responses=1
@@ -2345,29 +2375,29 @@ Inquiry result #0
Clock offset: 0x78ef
Inquiry complete. Status: No error [00]</screen>
- <para><literal>BD_ADDR</literal> is unique address of a
- Bluetooth device, similar to MAC addresses of a network card.
- This address is needed for further communication with a
- device. It is possible to assign human readable name to a
- BD_ADDR. The <filename>/etc/bluetooth/hosts</filename> file
- contains information regarding the known Bluetooth hosts. The
- following example shows how to obtain human readable name that
+ <para>The <literal>BD_ADDR</literal> is the unique address of a
+ Bluetooth device, similar to the <acronym>MAC</acronym>
+ address of a network card. This address is needed for
+ further communication with a device. It is possible to
+ assign a human readable name to a BD_ADDR. Information
+ regarding the known Bluetooth hosts is contained in
+ <filename>/etc/bluetooth/hosts</filename>. The following
+ example shows how to obtain the human readable name that
was assigned to the remote device:</para>
<screen>&prompt.user; <userinput>hccontrol -n ubt0hci remote_name_request 00:80:37:29:19:a4</userinput>
BD_ADDR: 00:80:37:29:19:a4
Name: Pav's T39</screen>
- <para>If you perform an inquiry on a remote Bluetooth device, it
- will find your computer as
+ <para>If an inquiry is performed on a remote Bluetooth device,
+ it will find the computer as
<quote>your.host.name (ubt0)</quote>. The name assigned to the
local device can be changed at any time.</para>
<para>The Bluetooth system provides a point-to-point connection
- (only two Bluetooth units involved), or a point-to-multipoint
- connection. In the point-to-multipoint connection the
- connection is shared among several Bluetooth devices. The
- following example shows how to obtain the list of active
+ between two Bluetooth units, or a point-to-multipoint
+ connection which is shared among several Bluetooth devices.
+ The following example shows how to obtain the list of active
baseband connections for the local device:</para>
<screen>&prompt.user; <userinput>hccontrol -n ubt0hci read_connection_list</userinput>
@@ -2375,8 +2405,8 @@ Remote BD_ADDR Handle Type Mode Role Encrypt Pending Queue State
00:80:37:29:19:a4 41 ACL 0 MAST NONE 0 0 OPEN</screen>
<para>A <emphasis>connection handle</emphasis> is useful when
- termination of the baseband connection is required. Note,
- that it is normally not required to do it by hand. The stack
+ termination of the baseband connection is required, though
+ it is normally not required to do this by hand. The stack
will automatically terminate inactive baseband
connections.</para>
@@ -2384,47 +2414,49 @@ Remote BD_ADDR Handle Type Mode Role Encrypt Pending Queue State
Connection handle: 41
Reason: Connection terminated by local host [0x16]</screen>
- <para>Refer to <command>hccontrol help</command> for a complete
- listing of available HCI commands. Most of the HCI commands
- do not require superuser privileges.</para>
+ <para>Type <command>hccontrol help</command> for a complete
+ listing of available <acronym>HCI</acronym> commands. Most
+ of the <acronym>HCI</acronym> commands do not require
+ superuser privileges.</para>
</sect2>
<sect2>
<title>Logical Link Control and Adaptation Protocol
- (L2CAP)</title>
+ (<acronym>L2CAP</acronym>)</title>
<indexterm><primary>L2CAP</primary></indexterm>
- <para>Logical Link Control and Adaptation Protocol (L2CAP)
- provides connection-oriented and connectionless data services
- to upper layer protocols with protocol multiplexing capability
- and segmentation and reassembly operation. L2CAP permits
+ <para>The Logical Link Control and Adaptation Protocol
+ (<acronym>L2CAP</acronym>) provides connection-oriented and
+ connectionless data services to upper layer protocols with
+ protocol multiplexing capability and segmentation and
+ reassembly operation. <acronym>L2CAP</acronym> permits
higher level protocols and applications to transmit and
- receive L2CAP data packets up to 64 kilobytes in
- length.</para>
+ receive <acronym>L2CAP</acronym> data packets up to 64
+ kilobytes in length.</para>
- <para>L2CAP is based around the concept of
- <emphasis>channels</emphasis>. Channel is a logical
- connection on top of baseband connection. Each channel is
+ <para><acronym>L2CAP</acronym> is based around the concept of
+ <emphasis>channels</emphasis>. A channel is a logical
+ connection on top of a baseband connection. Each channel is
bound to a single protocol in a many-to-one fashion. Multiple
channels can be bound to the same protocol, but a channel
- cannot be bound to multiple protocols. Each L2CAP packet
- received on a channel is directed to the appropriate higher
- level protocol. Multiple channels can share the same baseband
- connection.</para>
-
- <para>A single Netgraph node of type <emphasis>l2cap</emphasis>
- is created for a single Bluetooth device. The L2CAP node is
- normally connected to the Bluetooth HCI node (downstream) and
- Bluetooth sockets nodes (upstream). Default name for the
- L2CAP node is <quote>devicel2cap</quote>. For more details
- refer to the &man.ng.l2cap.4; manual page.</para>
+ cannot be bound to multiple protocols. Each
+ <acronym>L2CAP</acronym> packet received on a channel is
+ directed to the appropriate higher level protocol. Multiple
+ channels can share the same baseband connection.</para>
+
+ <para>A single netgraph node of type <emphasis>l2cap</emphasis>
+ is created for a single Bluetooth device. The
+ <acronym>L2CAP</acronym> node is normally connected to the
+ downstream Bluetooth <acronym>HCI</acronym> node and upstream
+ Bluetooth socket nodes. The default name for the
+ <acronym>L2CAP</acronym> node is <quote>devicel2cap</quote>.
+ For more details refer to &man.ng.l2cap.4;.</para>
<para>A useful command is &man.l2ping.8;, which can be used to
ping other devices. Some Bluetooth implementations might not
- return all of the data sent to them, so
- <literal>0 bytes</literal> in the following example is
- normal.</para>
+ return all of the data sent to them, so <literal>0
+ bytes</literal> in the following example is normal.</para>
<screen>&prompt.root; <userinput>l2ping -a 00:80:37:29:19:a4</userinput>
0 bytes from 0:80:37:29:19:a4 seq_no=0 time=48.633 ms result=0
@@ -2433,9 +2465,10 @@ Reason: Connection terminated by local host [0x16]</screen>
0 bytes from 0:80:37:29:19:a4 seq_no=3 time=46.150 ms result=0</screen>
<para>The &man.l2control.8; utility is used to perform various
- operations on L2CAP nodes. This example shows how to obtain
- the list of logical connections (channels) and the list of
- baseband connections for the local device:</para>
+ operations on <acronym>L2CAP</acronym> nodes. This example
+ shows how to obtain the list of logical connections (channels)
+ and the list of baseband connections for the local
+ device:</para>
<screen>&prompt.user; <userinput>l2control -a 00:02:72:00:d4:1a read_channel_list</userinput>
L2CAP channels:
@@ -2446,10 +2479,10 @@ L2CAP connections:
Remote BD_ADDR Handle Flags Pending State
00:07:e0:00:0b:ca 41 O 0 OPEN</screen>
- <para>Another diagnostic tool is &man.btsockstat.1;. It does a
- job similar to as &man.netstat.1; does, but for Bluetooth
- network-related data structures. The example below shows the
- same logical connection as &man.l2control.8; above.</para>
+ <para>Another diagnostic tool is &man.btsockstat.1;. It is
+ similar to &man.netstat.1;, but for Bluetooth network-related
+ data structures. The example below shows the same logical
+ connection as &man.l2control.8; above.</para>
<screen>&prompt.user; <userinput>btsockstat</userinput>
Active L2CAP sockets
@@ -2464,32 +2497,35 @@ c2e8bc80 0 250 00:02:72:00:d4:1a 00:07:e0:00:0b:ca 3 6 OPEN</scree
</sect2>
<sect2>
- <title>RFCOMM Protocol</title>
+ <title><acronym>RFCOMM</acronym> Protocol</title>
- <para>The RFCOMM protocol provides emulation of serial ports
- over the L2CAP protocol. The protocol is based on the ETSI
- standard TS 07.10. RFCOMM is a simple transport protocol,
+ <para>The <acronym>RFCOMM</acronym> protocol provides emulation
+ of serial ports over the <acronym>L2CAP</acronym> protocol.
+ The protocol is based on the ETSI standard TS 07.10.
+ <acronym>RFCOMM</acronym> is a simple transport protocol,
with additional provisions for emulating the 9 circuits of
- RS-232 (EIATIA-232-E) serial ports. The RFCOMM protocol
- supports up to 60 simultaneous connections (RFCOMM channels)
- between two Bluetooth devices.</para>
-
- <para>For the purposes of RFCOMM, a complete communication path
- involves two applications running on different devices (the
- communication endpoints) with a communication segment between
- them. RFCOMM is intended to cover applications that make use
- of the serial ports of the devices in which they reside. The
- communication segment is a Bluetooth link from one device to
- another (direct connect).</para>
-
- <para>RFCOMM is only concerned with the connection between the
- devices in the direct connect case, or between the device and
- a modem in the network case. RFCOMM can support other
- configurations, such as modules that communicate via Bluetooth
- wireless technology on one side and provide a wired interface
- on the other side.</para>
-
- <para>In &os; the RFCOMM protocol is implemented at the
+ RS-232 (EIATIA-232-E) serial ports. <acronym>RFCOMM</acronym>
+ supports up to 60 simultaneous connections
+ (<acronym>RFCOMM</acronym> channels) between two Bluetooth
+ devices.</para>
+
+ <para>For the purposes of <acronym>RFCOMM</acronym>, a complete
+ communication path involves two applications running on the
+ communication endpoints with a communication segment between
+ them. <acronym>RFCOMM</acronym> is intended to cover
+ applications that make use of the serial ports of the devices
+ in which they reside. The communication segment is a direct
+ connect Bluetooth link from one device to another.</para>
+
+ <para><acronym>RFCOMM</acronym> is only concerned with the
+ connection between the devices in the direct connect case,
+ or between the device and a modem in the network case.
+ <acronym>RFCOMM</acronym> can support other configurations,
+ such as modules that communicate via Bluetooth wireless
+ technology on one side and provide a wired interface on the
+ other side.</para>
+
+ <para>In &os;, <acronym>RFCOMM</acronym> is implemented at the
Bluetooth sockets layer.</para>
</sect2>
@@ -2498,26 +2534,27 @@ c2e8bc80 0 250 00:02:72:00:d4:1a 00:07:e0:00:0b:ca 3 6 OPEN</scree
<para>By default, Bluetooth communication is not authenticated,
and any device can talk to any other device. A Bluetooth
- device (for example, cellular phone) may choose to require
- authentication to provide a particular service (for example,
- Dial-Up service). Bluetooth authentication is normally done
- with <emphasis>PIN codes</emphasis>. A PIN code is an ASCII
- string up to 16 characters in length. User is required to
- enter the same PIN code on both devices. Once user has
- entered the PIN code, both devices will generate a
- <emphasis>link key</emphasis>. After that the link key can be
- stored either in the devices themselves or in a persistent
- storage. Next time both devices will use previously generated
- link key. The described above procedure is called
- <emphasis>pairing</emphasis>. Note that if the link key is
- lost by any device then pairing must be repeated.</para>
-
- <para>The &man.hcsecd.8; daemon is responsible for handling of
- all Bluetooth authentication requests. The default
- configuration file is
- <filename>/etc/bluetooth/hcsecd.conf</filename>. An example
- section for a cellular phone with the PIN code arbitrarily set
- to <quote>1234</quote> is shown below:</para>
+ device, such as a cellular phone, may choose to require
+ authentication to provide a particular service. Bluetooth
+ authentication is normally done with a
+ <emphasis><acronym>PIN</acronym> code</emphasis>, an ASCII
+ string up to 16 characters in length. The user is required
+ to enter the same <acronym>PIN</acronym> code on both devices.
+ Once the user has entered the <acronym>PIN</acronym> code,
+ both devices will generate a <emphasis>link key</emphasis>.
+ After that, the link key can be stored either in the devices
+ or in a persistent storage. Next time, both devices will
+ use the previously generated link key. This procedure is
+ called <emphasis>pairing</emphasis>. Note that if the link
+ key is lost by either device, the pairing must be
+ repeated.</para>
+
+ <para>The &man.hcsecd.8; daemon is responsible for handling
+ Bluetooth authentication requests. The default configuration
+ file is <filename>/etc/bluetooth/hcsecd.conf</filename>. An
+ example section for a cellular phone with the
+ <acronym>PIN</acronym> code arbitrarily set to
+ <quote>1234</quote> is shown below:</para>
<programlisting>device {
bdaddr 00:80:37:29:19:a4;
@@ -2526,27 +2563,28 @@ c2e8bc80 0 250 00:02:72:00:d4:1a 00:07:e0:00:0b:ca 3 6 OPEN</scree
pin "1234";
}</programlisting>
- <para>There is no limitation on PIN codes (except length). Some
- devices (for example Bluetooth headsets) may have a fixed PIN
- code built in. The <option>-d</option> switch forces the
- &man.hcsecd.8; daemon to stay in the foreground, so it is easy
- to see what is happening. Set the remote device to receive
- pairing and initiate the Bluetooth connection to the remote
- device. The remote device should say that pairing was
- accepted, and request the PIN code. Enter the same PIN code
- as you have in <filename>hcsecd.conf</filename>. Now your PC
- and the remote device are paired. Alternatively, you can
- initiate pairing on the remote device.</para>
-
- <para>The following line can be added to the
- <filename>/etc/rc.conf</filename> file to have
- <application>hcsecd</application> started automatically on
- system start:</para>
+ <para>The only limitation on <acronym>PIN</acronym> codes is
+ length. Some devices, such as Bluetooth headsets, may have
+ a fixed <acronym>PIN</acronym> code built in. The
+ <option>-d</option> switch forces &man.hcsecd.8; to stay in
+ the foreground, so it is easy to see what is happening. Set
+ the remote device to receive pairing and initiate the
+ Bluetooth connection to the remote device. The remote device
+ should indicate that pairing was accepted and request the
+ <acronym>PIN</acronym> code. Enter the same
+ <acronym>PIN</acronym> code listed in
+ <filename>hcsecd.conf</filename>. Now the computer and the
+ remote device are paired. Alternatively, pairing can be
+ initiated on the remote device.</para>
+
+ <para>The following line can be added to
+ <filename>/etc/rc.conf</filename> to configure &man.hcsecd.8;
+ to start automatically on system start:</para>
<programlisting>hcsecd_enable="YES"</programlisting>
- <para>The following is a sample of the
- <application>hcsecd</application> daemon output:</para>
+ <para>The following is a sample of the &man.hcsecd.8; daemon
+ output:</para>
<programlisting>hcsecd[16484]: Got Link_Key_Request event from 'ubt0hci', remote bdaddr 0:80:37:29:19:a4
hcsecd[16484]: Found matching entry, remote bdaddr 0:80:37:29:19:a4, name 'Pav's T39', link key doesn't exist
@@ -2557,42 +2595,47 @@ hcsecd[16484]: Sending PIN_Code_Reply to 'ubt0hci' for remote bdaddr 0:80:37:29:
</sect2>
<sect2>
- <title>Service Discovery Protocol (SDP)</title>
+ <title>Service Discovery Protocol
+ (<acronym>SDP</acronym>)</title>
<indexterm><primary>SDP</primary></indexterm>
- <para>The Service Discovery Protocol (SDP) provides the means
- for client applications to discover the existence of services
- provided by server applications as well as the attributes of
- those services. The attributes of a service include the type
- or class of service offered and the mechanism or protocol
- information needed to utilize the service.</para>
+ <para>The Service Discovery Protocol (<acronym>SDP</acronym>)
+ provides the means for client applications to discover the
+ existence of services provided by server applications as well
+ as the attributes of those services. The attributes of a
+ service include the type or class of service offered and the
+ mechanism or protocol information needed to utilize the
+ service.</para>
- <para>SDP involves communication between a SDP server and a SDP
+ <para><acronym>SDP</acronym> involves communication between a
+ <acronym>SDP</acronym> server and a <acronym>SDP</acronym>
client. The server maintains a list of service records that
describe the characteristics of services associated with the
server. Each service record contains information about a
single service. A client may retrieve information from a
- service record maintained by the SDP server by issuing a SDP
- request. If the client, or an application associated with the
- client, decides to use a service, it must open a separate
- connection to the service provider in order to utilize the
- service. SDP provides a mechanism for discovering services
- and their attributes, but it does not provide a mechanism for
- utilizing those services.</para>
-
- <para>Normally, a SDP client searches for services based on some
- desired characteristics of the services. However, there are
- times when it is desirable to discover which types of services
- are described by an SDP server's service records without any a
- priori information about the services. This process of
+ service record maintained by the <acronym>SDP</acronym> server
+ by issuing a <acronym>SDP</acronym> request. If the client,
+ or an application associated with the client, decides to use
+ a service, it must open a separate connection to the service
+ provider in order to utilize the service.
+ <acronym>SDP</acronym> provides a mechanism for discovering
+ services and their attributes, but it does not provide a
+ mechanism for utilizing those services.</para>
+
+ <para>Normally, a <acronym>SDP</acronym> client searches for
+ services based on some desired characteristics of the
+ services. However, there are times when it is desirable to
+ discover which types of services are described by an
+ <acronym>SDP</acronym> server's service records without any
+ prior information about the services. This process of
looking for any offered services is called
<emphasis>browsing</emphasis>.</para>
- <para>The Bluetooth SDP server &man.sdpd.8; and command line
- client &man.sdpcontrol.8; are included in the standard &os;
- installation. The following example shows how to perform a
- SDP browse query.</para>
+ <para>The Bluetooth <acronym>SDP</acronym> server, &man.sdpd.8;,
+ and command line client, &man.sdpcontrol.8;, are included in
+ the standard &os; installation. The following example shows
+ how to perform a <acronym>SDP</acronym> browse query.</para>
<screen>&prompt.user; <userinput>sdpcontrol -a 00:01:03:fc:6e:ec browse</userinput>
Record Handle: 00000000
@@ -2617,137 +2660,158 @@ Protocol Descriptor List:
Bluetooth Profile Descriptor List:
LAN Access Using PPP (0x1102) ver. 1.0</screen>
- <para>... and so on. Note that each service has a list of
- attributes (RFCOMM channel for example). Depending on the
- service you might need to make a note of some of the
+ <para>Note that each service has a list of attributes, such
+ as the <acronym>RFCOMM</acronym> channel. Depending on the
+ service, the user might need to make note of some of the
attributes. Some Bluetooth implementations do not support
- service browsing and may return an empty list. In this case
+ service browsing and may return an empty list. In this case,
it is possible to search for the specific service. The
- example below shows how to search for the OBEX Object Push
- (OPUSH) service:</para>
+ example below shows how to search for the
+ <acronym>OBEX</acronym> Object Push
+ (<acronym>OPUSH</acronym>) service:</para>
<screen>&prompt.user; <userinput>sdpcontrol -a 00:01:03:fc:6e:ec search OPUSH</userinput></screen>
<para>Offering services on &os; to Bluetooth clients is done
with the &man.sdpd.8; server. The following line can be added
- to the <filename>/etc/rc.conf</filename> file:</para>
+ to <filename>/etc/rc.conf</filename>:</para>
<programlisting>sdpd_enable="YES"</programlisting>
- <para>Then the <application>sdpd</application> daemon can be
+ <para>Then the &man.sdpd.8; daemon can be
started with:</para>
<screen>&prompt.root; <userinput>service sdpd start</userinput></screen>
<para>The local server application that wants to provide
Bluetooth service to the remote clients will register service
- with the local SDP daemon. The example of such application is
- &man.rfcomm.pppd.8;. Once started it will register Bluetooth
- LAN service with the local SDP daemon.</para>
-
- <para>The list of services registered with the local SDP server
- can be obtained by issuing SDP browse query via local control
+ with the local <acronym>SDP</acronym> daemon. An example of
+ such an application is &man.rfcomm.pppd.8;. Once started,
+ it will register the Bluetooth LAN service with the local
+ <acronym>SDP</acronym> daemon.</para>
+
+ <para>The list of services registered with the local
+ <acronym>SDP</acronym> server can be obtained by issuing a
+ <acronym>SDP</acronym> browse query via the local control
channel:</para>
<screen>&prompt.root; <userinput>sdpcontrol -l browse</userinput></screen>
</sect2>
<sect2>
- <title>Dial-Up Networking (DUN) and Network Access with PPP
- (LAN) Profiles</title>
+ <title>Dial-Up Networking and Network Access with
+ <acronym>PPP</acronym> Profiles</title>
- <para>The Dial-Up Networking (DUN) profile is mostly used with
- modems and cellular phones. The scenarios covered by this
- profile are the following:</para>
+ <para>The Dial-Up Networking (<acronym>DUN</acronym>) profile is
+ mostly used with modems and cellular phones. The scenarios
+ covered by this profile are the following:</para>
<itemizedlist>
<listitem>
- <para>use of a cellular phone or modem by a computer as a
+ <para>Use of a cellular phone or modem by a computer as a
wireless modem for connecting to a dial-up Internet access
- server, or using other dial-up services;</para>
+ server, or for using other dial-up services.</para>
</listitem>
<listitem>
- <para>use of a cellular phone or modem by a computer to
+ <para>Use of a cellular phone or modem by a computer to
receive data calls.</para>
</listitem>
</itemizedlist>
- <para>Network Access with PPP (LAN) profile can be used in the
- following situations:</para>
+ <para>Network access with a <acronym>PPP</acronym> profile can
+ be used in the following situations:</para>
<itemizedlist>
<listitem>
- <para>LAN access for a single Bluetooth device;</para>
+ <para><acronym>LAN</acronym> access for a single Bluetooth
+ device.</para>
</listitem>
<listitem>
- <para>LAN access for multiple Bluetooth devices;</para>
+ <para><acronym>LAN</acronym> access for multiple Bluetooth
+ devices.</para>
</listitem>
<listitem>
- <para>PC to PC (using PPP networking over serial cable
- emulation).</para>
+ <para>PC to PC connection using <acronym>PPP</acronym>
+ networking over serial cable emulation.</para>
</listitem>
</itemizedlist>
- <para>In &os; both profiles are implemented with &man.ppp.8; and
- &man.rfcomm.pppd.8; - a wrapper that converts RFCOMM Bluetooth
- connection into something PPP can operate with. Before any
- profile can be used, a new PPP label in the
- <filename>/etc/ppp/ppp.conf</filename> must be created.
- Consult &man.rfcomm.pppd.8; manual page for examples.</para>
-
- <para>In the following example &man.rfcomm.pppd.8; will be used
- to open RFCOMM connection to remote device with BD_ADDR
- 00:80:37:29:19:a4 on DUN RFCOMM channel. The actual RFCOMM
- channel number will be obtained from the remote device via
- SDP. It is possible to specify RFCOMM channel by hand, and in
- this case &man.rfcomm.pppd.8; will not perform SDP query. Use
- &man.sdpcontrol.8; to find out RFCOMM channel on the remote
- device.</para>
+ <para>In &os;, these profiles are implemented with &man.ppp.8;
+ and the &man.rfcomm.pppd.8; wrapper which converts a
+ <acronym>RFCOMM</acronym> Bluetooth connection into something
+ <acronym>PPP</acronym> can use. Before a profile can be used,
+ a new <acronym>PPP</acronym> label must be created in
+ <filename>/etc/ppp/ppp.conf</filename>. Consult
+ &man.rfcomm.pppd.8; for examples.</para>
+
+ <para>In the following example, &man.rfcomm.pppd.8; is used
+ to open a <acronym>RFCOMM</acronym> connection to a remote
+ device with a BD_ADDR of <literal>00:80:37:29:19:a4</literal>
+ on a <acronym>DUN</acronym> <acronym>RFCOMM</acronym> channel.
+ The actual <acronym>RFCOMM</acronym> channel number will be
+ obtained from the remote device via <acronym>SDP</acronym>.
+ It is possible to specify the <acronym>RFCOMM</acronym>
+ channel by hand, and in this case &man.rfcomm.pppd.8; will
+ not perform the <acronym>SDP</acronym> query. Use
+ &man.sdpcontrol.8; to find out the <acronym>RFCOMM</acronym>
+ channel on the remote device.</para>
<screen>&prompt.root; <userinput>rfcomm_pppd -a 00:80:37:29:19:a4 -c -C dun -l rfcomm-dialup</userinput></screen>
- <para>In order to provide Network Access with PPP (LAN) service
- the &man.sdpd.8; server must be running. A new entry for LAN
- clients must be created in the
- <filename>/etc/ppp/ppp.conf</filename> file. Consult
- &man.rfcomm.pppd.8; manual page for examples. Finally, start
- RFCOMM PPP server on valid RFCOMM channel number. The RFCOMM
- PPP server will automatically register Bluetooth LAN service
- with the local SDP daemon. The example below shows how to
- start RFCOMM PPP server.</para>
+ <para>In order to provide network access with the
+ <acronym>PPP</acronym> <acronym>LAN</acronym> service,
+ &man.sdpd.8; must be running and a new entry for
+ <acronym>LAN</acronym> clients must be created in
+ <filename>/etc/ppp/ppp.conf</filename>. Consult
+ &man.rfcomm.pppd.8; for examples. Finally, start the
+ <acronym>RFCOMM</acronym> <acronym>PPP</acronym> server on a
+ valid <acronym>RFCOMM</acronym> channel number. The
+ <acronym>RFCOMM</acronym> <acronym>PPP</acronym> server will
+ automatically register the Bluetooth <acronym>LAN</acronym>
+ service with the local <acronym>SDP</acronym> daemon. The
+ example below shows how to start the <acronym>RFCOMM</acronym>
+ <acronym>PPP</acronym> server.</para>
<screen>&prompt.root; <userinput>rfcomm_pppd -s -C 7 -l rfcomm-server</userinput></screen>
</sect2>
<sect2>
- <title>OBEX Object Push (OPUSH) Profile</title>
+ <title><acronym>OBEX</acronym> Object Push
+ (<acronym>OPUSH</acronym>) Profile</title>
<indexterm><primary>OBEX</primary></indexterm>
- <para>OBEX is a widely used protocol for simple file transfers
- between mobile devices. Its main use is in infrared
- communication, where it is used for generic file transfers
- between notebooks or PDAs, and for sending business cards or
- calendar entries between cellular phones and other devices
- with PIM applications.</para>
-
- <para>The OBEX server and client are implemented as a
- third-party package <application>obexapp</application>, which
- is available as <filename
- role="package">comms/obexapp</filename> port.</para>
-
- <para>OBEX client is used to push and/or pull objects from the
- OBEX server. An object can, for example, be a business card
- or an appointment. The OBEX client can obtain RFCOMM channel
- number from the remote device via SDP. This can be done by
- specifying service name instead of RFCOMM channel number.
- Supported service names are: IrMC, FTRN and OPUSH. It is
- possible to specify RFCOMM channel as a number. Below is an
- example of an OBEX session, where device information object is
- pulled from the cellular phone, and a new object (business
- card) is pushed into the phone's directory.</para>
+ <para><acronym>OBEX</acronym> is a widely used protocol for
+ simple file transfers between mobile devices. Its main use
+ is in infrared communication, where it is used for generic
+ file transfers between notebooks or <acronym>PDA</acronym>s,
+ and for sending business cards or calendar entries between
+ cellular phones and other devices with <acronym>PIM</acronym>
+ applications.</para>
+
+ <para>The <acronym>OBEX</acronym> server and client are
+ implemented as a third-party package,
+ <application>obexapp</application>, which is available as
+ <filename role="package">comms/obexapp</filename> package or
+ port.</para>
+
+ <para>The <acronym>OBEX</acronym> client is used to push and/or
+ pull objects from the <acronym>OBEX</acronym> server. An
+ object can, for example, be a business card or an appointment.
+ The <acronym>OBEX</acronym> client can obtain the
+ <acronym>RFCOMM</acronym> channel number from the remote
+ device via <acronym>SDP</acronym>. This can be done by
+ specifying the service name instead of the
+ <acronym>RFCOMM</acronym> channel number. Supported service
+ names are: <acronym>IrMC</acronym>, <acronym>FTRN</acronym>,
+ and <acronym>OPUSH</acronym>. It is also possible to specify
+ the <acronym>RFCOMM</acronym> channel as a number. Below is
+ an example of an <acronym>OBEX</acronym> session where the
+ device information object is pulled from the cellular phone,
+ and a new object, the business card, is pushed into the
+ phone's directory.</para>
<screen>&prompt.user; <userinput>obexapp -a 00:80:37:29:19:a4 -C IrMC</userinput>
obex&gt; get telecom/devinfo.txt devinfo-t39.txt
@@ -2757,35 +2821,38 @@ Success, response: OK, Success (0x20)
obex&gt; di
Success, response: OK, Success (0x20)</screen>
- <para>In order to provide OBEX Object Push service, &man.sdpd.8;
- server must be running. A root folder, where all incoming
- objects will be stored, must be created. The default path to
- the root folder
- is <filename class="directory">/var/spool/obex</filename>.
- Finally, start OBEX server on valid RFCOMM channel number.
- The OBEX server will automatically register OBEX Object Push
- service with the local SDP daemon. The example below shows
- how to start OBEX server.</para>
+ <para>In order to provide the <acronym>OPUSH</acronym> service,
+ &man.sdpd.8; must be running and a root folder, where all
+ incoming objects will be stored, must be created. The
+ default path to the root folder is <filename
+ class="directory">/var/spool/obex</filename>. Finally,
+ start the <acronym>OBEX</acronym> server on a valid
+ <acronym>RFCOMM</acronym> channel number. The
+ <acronym>OBEX</acronym> server will automatically register
+ the <acronym>OPUSH</acronym> service with the local
+ <acronym>SDP</acronym> daemon. The example below shows how
+ to start the <acronym>OBEX</acronym> server.</para>
<screen>&prompt.root; <userinput>obexapp -s -C 10</userinput></screen>
</sect2>
<sect2>
- <title>Serial Port Profile (SPP)</title>
-
- <para>The Serial Port Profile (SPP) allows Bluetooth devices to
- perform RS232 (or similar) serial cable emulation. The
- scenario covered by this profile deals with legacy
- applications using Bluetooth as a cable replacement, through a
- virtual serial port abstraction.</para>
-
- <para>The &man.rfcomm.sppd.1; utility implements the Serial Port
- profile. A pseudo tty is used as a virtual serial port
- abstraction. The example below shows how to connect to a
- remote device Serial Port service. Note that you do not have
- to specify a RFCOMM channel - &man.rfcomm.sppd.1; can obtain
- it from the remote device via SDP. If you would like to
- override this, specify a RFCOMM channel on the command
+ <title>Serial Port Profile</title>
+
+ <para>The Serial Port Profile (<acronym>SPP</acronym>) allows
+ Bluetooth devices to perform serial cable emulation. This
+ profile allows legacy applications to use Bluetooth as a
+ cable replacement, through a virtual serial port
+ abstraction.</para>
+
+ <para>In &os;, &man.rfcomm.sppd.1; implements
+ <acronym>SPP</acronym> and a pseudo tty is used as a virtual
+ serial port abstraction. The example below shows how to
+ connect to a remote device serial port service. A
+ <acronym>RFCOMM</acronym> channel does not have to be
+ specified as &man.rfcomm.sppd.1; can obtain it from the
+ remote device via <acronym>SDP</acronym>. To override this,
+ specify a <acronym>RFCOMM</acronym> channel on the command
line.</para>
<screen>&prompt.root; <userinput>rfcomm_sppd -a 00:07:E0:00:0B:CA -t /dev/ttyp6</userinput>
@@ -2807,26 +2874,25 @@ rfcomm_sppd[94692]: Starting on /dev/ttyp6...</screen>
switching. By default, when &os; is accepting a new
connection, it tries to perform a role switch and become
master. Devices, which do not support this will not be able
- to connect. Note that role switching is performed when a
- new connection is being established, so it is not possible
- to ask the remote device if it does support role switching.
- There is a HCI option to disable role switching on the local
- side:</para>
+ to connect. Since role switching is performed when a
+ new connection is being established, it is not possible
+ to ask the remote device if it supports role switching.
+ There is a <acronym>HCI</acronym> option to disable role
+ switching on the local side:</para>
<screen>&prompt.root; <userinput>hccontrol -n ubt0hci write_node_role_switch 0</userinput></screen>
</sect3>
<sect3>
- <title>Something is Going Wrong, Can I See What Exactly is
- Happening?</title>
-
- <para>Yes, you can. Use the third-party package
- <application>hcidump</application>, which is available as
- <filename role="package">comms/hcidump</filename> port. The
- <application>hcidump</application> utility is similar to
- &man.tcpdump.1;. It can be used to display the content of
- the Bluetooth packets on the terminal and to dump the
- Bluetooth packets to a file.</para>
+ <title>Displaying Bluetooth Packets</title>
+
+ <para>Use the third-party package
+ <application>hcidump</application>, which is available as a
+ <filename role="package">comms/hcidump</filename> package or
+ port. This utility is similar to &man.tcpdump.1; and can
+ be used to display the contents of Bluetooth packets on
+ the terminal and to dump the Bluetooth packets to a
+ file.</para>
</sect3>
</sect2>
</sect1>
@@ -2846,20 +2912,21 @@ rfcomm_sppd[94692]: Starting on /dev/ttyp6...</screen>
<sect2>
<title>Introduction</title>
- <indexterm><primary>IP subnet</primary></indexterm>
+ <indexterm><primary><acronym>IP</acronym>
+ subnet</primary></indexterm>
<indexterm><primary>bridge</primary></indexterm>
- <para>It is sometimes useful to divide one physical network
- (such as an Ethernet segment) into two separate network
- segments without having to create IP subnets and use a router
- to connect the segments together. A device that connects two
- networks together in this fashion is called a
- <quote>bridge</quote>. A FreeBSD system with two network
- interface cards can act as a bridge.</para>
-
- <para>The bridge works by learning the MAC layer addresses
- (Ethernet addresses) of the devices on each of its network
- interfaces. It forwards traffic between two networks only
- when its source and destination are on different
+ <para>It is sometimes useful to divide one physical network,
+ such as an Ethernet segment, into two separate network
+ segments without having to create <acronym>IP</acronym>
+ subnets and use a router to connect the segments together.
+ A device that connects two networks together in this fashion
+ is called a <quote>bridge</quote>. A &os; system with two
+ network interface cards can act as a bridge.</para>
+
+ <para>The bridge works by learning the <acronym>MAC</acronym>
+ layer (Ethernet) addresses of the devices on each of its
+ network interfaces. It forwards traffic between two networks
+ only when the source and destination are on different
networks.</para>
<para>In many respects, a bridge is like an Ethernet switch with
@@ -2878,8 +2945,8 @@ rfcomm_sppd[94692]: Starting on /dev/ttyp6...</screen>
<para>The basic operation of a bridge is to join two or more
network segments together. There are many reasons to use a
host based bridge over plain networking equipment such as
- cabling constraints, firewalling or connecting pseudo
- networks such as a Virtual Machine interface. A bridge can
+ cabling constraints, firewalling, or connecting pseudo
+ networks such as a virtual machine interface. A bridge can
also connect a wireless interface running in hostap mode to
a wired network and act as an access point.</para>
</sect3>
@@ -2891,68 +2958,73 @@ rfcomm_sppd[94692]: Starting on /dev/ttyp6...</screen>
<indexterm><primary>NAT</primary></indexterm>
<para>A common situation is where firewall functionality is
- needed without routing or network address translation
- (NAT).</para>
+ needed without routing or Network Address Translation
+ (<acronym>NAT</acronym>).</para>
- <para>An example is a small company that is connected via DSL
- or ISDN to their ISP. They have a 13 globally-accessible IP
- addresses from their ISP and have 10 PCs on their network.
- In this situation, using a router-based firewall is
- difficult because of subnetting issues.</para>
+ <para>An example is a small company that is connected via
+ <acronym>DSL</acronym>
+ or <acronym>ISDN</acronym> to an <acronym>ISP</acronym>.
+ There are thirteen globally-accessible <acronym>IP</acronym>
+ addresses from the <acronym>ISP</acronym> and ten computers
+ on the network. In this situation, using a router-based
+ firewall is difficult because of subnetting issues.</para>
<indexterm><primary>router</primary></indexterm>
- <indexterm><primary>DSL</primary></indexterm>
- <indexterm><primary>ISDN</primary></indexterm>
+ <indexterm><primary><acronym>DSL</acronym></primary></indexterm>
+ <indexterm><primary><acronym>ISDN</acronym></primary></indexterm>
<para>A bridge-based firewall can be configured and dropped
- into the path just downstream of their DSL/ISDN router
- without any IP numbering issues.</para>
+ into the path just downstream of the <acronym>DSL</acronym>
+ or <acronym>ISDN</acronym> router without any
+ <acronym>IP</acronym> numbering issues.</para>
</sect3>
<sect3>
<title>Network Tap</title>
<para>A bridge can join two network segments and be used to
- inspect all Ethernet frames that pass between them. This
- can either be from using &man.bpf.4;/&man.tcpdump.1; on the
- bridge interface or by sending a copy of all frames out an
- additional interface (span port).</para>
+ inspect all Ethernet frames that pass between them using
+ &man.bpf.4; and &man.tcpdump.1; on the bridge interface or
+ by sending a copy of all frames out an additional interface
+ known as a span port.</para>
</sect3>
<sect3>
- <title>Layer 2 VPN</title>
+ <title>Layer 2 <acronym>VPN</acronym></title>
- <para>Two Ethernet networks can be joined across an IP link by
- bridging the networks to an EtherIP tunnel or a &man.tap.4;
- based solution such as OpenVPN.</para>
+ <para>Two Ethernet networks can be joined across an
+ <acronym>IP</acronym> link by bridging the networks to an
+ EtherIP tunnel or a &man.tap.4; based solution such as
+ <application>OpenVPN</application>.</para>
</sect3>
<sect3>
<title>Layer 2 Redundancy</title>
<para>A network can be connected together with multiple links
- and use the Spanning Tree Protocol to block redundant paths.
- For an Ethernet network to function properly only one active
- path can exist between two devices, Spanning Tree will
- detect loops and put the redundant links into a blocked
- state. Should one of the active links fail then the
- protocol will calculate a different tree and reenable one of
- the blocked paths to restore connectivity to all points in
- the network.</para>
+ and use the Spanning Tree Protocol <acronym>STP</acronym>
+ to block redundant paths. For an Ethernet network to
+ function properly, only one active path can exist between
+ two devices. <acronym>STP</acronym> will detect loops and
+ put the redundant links into a blocked state. Should one
+ of the active links fail, <acronym>STP</acronym> will
+ calculate a different tree and enable one of the blocked
+ paths to restore connectivity to all points in the
+ network.</para>
</sect3>
</sect2>
<sect2>
<title>Kernel Configuration</title>
- <para>This section covers &man.if.bridge.4; bridge
- implementation, a netgraph bridging driver is also available,
- for more information see &man.ng.bridge.4; manual page.</para>
+ <para>This section covers the &man.if.bridge.4; implementation.
+ A netgraph bridging driver is also available, and is described
+ in &man.ng.bridge.4;.</para>
- <para>The bridge driver is a kernel module and will be
+ <para>In &os;, &man.if.bridge.4; is a kernel module which is
automatically loaded by &man.ifconfig.8; when creating a
- bridge interface. It is possible to compile the bridge in to
- the kernel by adding <literal>device if_bridge</literal> to
- your kernel configuration file.</para>
+ bridge interface. It is also possible to compile the bridge
+ in to the kernel by adding <literal>device if_bridge</literal>
+ to a custom kernel configuration file.</para>
<para>Packet filtering can be used with any firewall package
that hooks in via the &man.pfil.9; framework. The firewall
@@ -2966,9 +3038,7 @@ rfcomm_sppd[94692]: Starting on /dev/ttyp6...</screen>
<title>Enabling the Bridge</title>
<para>The bridge is created using interface cloning. To create
- a bridge use &man.ifconfig.8;, if the bridge driver is not
- present in the kernel then it will be loaded
- automatically.</para>
+ a bridge use &man.ifconfig.8;:</para>
<screen>&prompt.root; <userinput>ifconfig bridge create</userinput>
bridge0
@@ -2979,17 +3049,18 @@ bridge0: flags=8802&lt;BROADCAST,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
maxage 20 holdcnt 6 proto rstp maxaddr 100 timeout 1200
root id 00:00:00:00:00:00 priority 0 ifcost 0 port 0</screen>
- <para>A bridge interface is created and is automatically
+ <para>When a bridge interface is created, it is automatically
assigned a randomly generated Ethernet address. The
<literal>maxaddr</literal> and <literal>timeout</literal>
- parameters control how many MAC addresses the bridge will keep
- in its forwarding table and how many seconds before each entry
- is removed after it is last seen. The other parameters
- control how Spanning Tree operates.</para>
+ parameters control how many <acronym>MAC</acronym> addresses
+ the bridge will keep in its forwarding table and how many
+ seconds before each entry is removed after it is last seen.
+ The other parameters control how <acronym>STP</acronym>
+ operates.</para>
- <para>Add the member network interfaces to the bridge. For the
- bridge to forward packets all member interfaces and the bridge
- need to be up:</para>
+ <para>Next, add the member network interfaces to the bridge.
+ For the bridge to forward packets, all member interfaces and
+ the bridge need to be up:</para>
<screen>&prompt.root; <userinput>ifconfig bridge0 addm fxp0 addm fxp1 up</userinput>
&prompt.root; <userinput>ifconfig fxp0 up</userinput>
@@ -2997,24 +3068,25 @@ bridge0: flags=8802&lt;BROADCAST,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
<para>The bridge is now forwarding Ethernet frames between
<devicename>fxp0</devicename> and
- <devicename>fxp1</devicename>. The equivalent configuration
- in <filename>/etc/rc.conf</filename> so the bridge is created
- at startup is:</para>
+ <devicename>fxp1</devicename>. Add the following lines to
+ <filename>/etc/rc.conf</filename> so the bridge is created
+ at startup:</para>
<programlisting>cloned_interfaces="bridge0"
ifconfig_bridge0="addm fxp0 addm fxp1 up"
ifconfig_fxp0="up"
ifconfig_fxp1="up"</programlisting>
- <para>If the bridge host needs an IP address then the correct
- place to set this is on the bridge interface itself rather
- than one of the member interfaces. This can be set statically
- or via DHCP:</para>
+ <para>If the bridge host needs an <acronym>IP</acronym>
+ address, the correct place to set this is on the bridge
+ interface itself rather than one of the member interfaces.
+ This can be set statically or via
+ <acronym>DHCP</acronym>:</para>
<screen>&prompt.root; <userinput>ifconfig bridge0 inet 192.168.0.1/24</userinput></screen>
- <para>It is also possible to assign an IPv6 address to a bridge
- interface.</para>
+ <para>It is also possible to assign an <acronym>IPv6</acronym>
+ address to a bridge interface.</para>
</sect2>
<sect2>
@@ -3023,14 +3095,15 @@ ifconfig_fxp1="up"</programlisting>
<indexterm><primary>firewall</primary></indexterm>
<para>When packet filtering is enabled, bridged packets will
- pass through the filter inbound on the originating interface,
- on the bridge interface and outbound on the appropriate
+ pass through the filter inbound on the originating interface
+ on the bridge interface, and outbound on the appropriate
interfaces. Either stage can be disabled. When direction of
- the packet flow is important it is best to firewall on the
+ the packet flow is important, it is best to firewall on the
member interfaces rather than the bridge itself.</para>
<para>The bridge has several configurable settings for passing
- non-IP and ARP packets, and layer2 firewalling with IPFW. See
+ non-<acronym>IP</acronym> and <acronym>IP</acronym> packets,
+ and layer2 firewalling with &man.ipfw.8;. See
&man.if.bridge.4; for more information.</para>
</sect2>
@@ -3038,21 +3111,22 @@ ifconfig_fxp1="up"</programlisting>
<title>Spanning Tree</title>
<para>The bridge driver implements the Rapid Spanning Tree
- Protocol (RSTP or 802.1w) with backwards compatibility with
- the legacy Spanning Tree Protocol (STP). Spanning Tree is
- used to detect and remove loops in a network topology. RSTP
- provides faster Spanning Tree convergence than legacy STP, the
- protocol will exchange information with neighbouring switches
- to quickly transition to forwarding without creating
- loops.
- &os; supports RSTP and STP as operating modes, with RSTP
- being the default mode.</para>
-
- <para>Spanning Tree can be enabled on member interfaces using
- the <literal>stp</literal> command. For a bridge with
+ Protocol (<acronym>RSTP</acronym> or 802.1w) with backwards
+ compatibility with legacy <acronym>STP</acronym>.
+ <acronym>STP</acronym> is used to detect and remove loops
+ in a network topology. <acronym>RSTP</acronym> provides
+ faster convergence than legacy <acronym>STP</acronym>, the
+ protocol will exchange information with neighboring switches
+ to quickly transition to forwarding without creating loops.
+ &os; supports <acronym>RSTP</acronym> and
+ <acronym>STP</acronym> as operating modes, with
+ <acronym>RSTP</acronym> being the default mode.</para>
+
+ <para><acronym>STP</acronym> can be enabled on member interfaces
+ using &man.ifconfig.8;. For a bridge with
<devicename>fxp0</devicename> and
<devicename>fxp1</devicename> as the current interfaces,
- enable STP with the following:</para>
+ enable <acronym>STP</acronym> with:</para>
<screen>&prompt.root; <userinput>ifconfig bridge0 stp fxp0 stp fxp1</userinput>
bridge0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
@@ -3070,11 +3144,11 @@ bridge0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1
<para>This bridge has a spanning tree ID of
<literal>00:01:02:4b:d4:50</literal> and a priority of
<literal>32768</literal>. As the <literal>root id</literal>
- is the same it indicates that this is the root bridge for the
+ is the same, it indicates that this is the root bridge for the
tree.</para>
- <para>Another bridge on the network also has spanning tree
- enabled:</para>
+ <para>Another bridge on the network also has
+ <acronym>STP</acronym> enabled:</para>
<screen>bridge0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
ether 96:3d:4b:f1:79:7a
@@ -3090,9 +3164,9 @@ bridge0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1
<para>The line <literal>root id 00:01:02:4b:d4:50 priority 32768
ifcost 400000 port 4</literal> shows that the root bridge is
- <literal>00:01:02:4b:d4:50</literal> as above and has a path
- cost of <literal>400000</literal> from this bridge, the path
- to the root bridge is via <literal>port 4</literal> which is
+ <literal>00:01:02:4b:d4:50</literal> and has a path cost of
+ <literal>400000</literal> from this bridge. The path to the
+ root bridge is via <literal>port 4</literal> which is
<devicename>fxp0</devicename>.</para>
</sect2>
@@ -3103,7 +3177,7 @@ bridge0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1
<title>Reconstruct Traffic Flows</title>
<para>The bridge supports monitor mode, where the packets are
- discarded after &man.bpf.4; processing, and are not
+ discarded after &man.bpf.4; processing and are not
processed or forwarded further. This can be used to
multiplex the input of two or more interfaces into a single
&man.bpf.4; stream. This is useful for reconstructing the
@@ -3122,9 +3196,9 @@ bridge0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1
<para>A copy of every Ethernet frame received by the bridge
will be transmitted out a designated span port. The number
- of span ports configured on a bridge is unlimited, if an
- interface is designated as a span port then it may not also
- be used as a regular bridge port. This is most useful for
+ of span ports configured on a bridge is unlimited, but if an
+ interface is designated as a span port, it cannot also be
+ used as a regular bridge port. This is most useful for
snooping a bridged network passively on another host
connected to one of the span ports of the bridge.</para>
@@ -3140,102 +3214,107 @@ bridge0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1
<para>A private interface does not forward any traffic to any
other port that is also a private interface. The traffic is
blocked unconditionally so no Ethernet frames will be
- forwarded, including ARP. If traffic needs to be
- selectively blocked then a firewall should be used
+ forwarded, including <acronym>ARP</acronym>. If traffic
+ needs to be selectively blocked, a firewall should be used
instead.</para>
</sect3>
<sect3>
<title>Sticky Interfaces</title>
- <para>If a bridge member interface is marked as sticky then
+ <para>If a bridge member interface is marked as sticky,
dynamically learned address entries are treated at static
once entered into the forwarding cache. Sticky entries are
never aged out of the cache or replaced, even if the address
is seen on a different interface. This gives the benefit of
static address entries without the need to pre-populate the
- forwarding table, clients learnt on a particular segment of
- the bridge can not roam to another segment.</para>
+ forwarding table. Clients learned on a particular segment
+ of the bridge can not roam to another segment.</para>
- <para>Another example of using sticky addresses would be to
- combine the bridge with VLANs to create a router where
- customer networks are isolated without wasting IP address
- space. Consider that
+ <para>Another example of using sticky addresses is to
+ combine the bridge with <acronym>VLAN</acronym>s to create
+ a router where customer networks are isolated without
+ wasting <acronym>IP</acronym> address space. Consider that
<hostid role="hostname">CustomerA</hostid> is on
- <literal>vlan100</literal> and
- <hostid role="hostname">CustomerB</hostid> is on
+ <literal>vlan100</literal> and <hostid
+ role="hostname">CustomerB</hostid> is on
<literal>vlan101</literal>. The bridge has the address
<hostid role="ipaddr">192.168.0.1</hostid> and is also an
- internet router.</para>
+ Internet router.</para>
<screen>&prompt.root; <userinput>ifconfig bridge0 addm vlan100 sticky vlan100 addm vlan101 sticky vlan101</userinput>
&prompt.root; <userinput>ifconfig bridge0 inet 192.168.0.1/24</userinput></screen>
- <para>Both clients see
- <hostid role="ipaddr">192.168.0.1</hostid> as their default
- gateway and since the bridge cache is sticky they can not
- spoof the MAC address of the other customer to intercept
- their traffic.</para>
+ <para>In this example, both clients see <hostid
+ role="ipaddr">192.168.0.1</hostid> as their default
+ gateway. Since the bridge cache is sticky, one host can not
+ spoof the <acronym>MAC</acronym> address of the other
+ customer in order to intercept their traffic.</para>
- <para>Any communication between the VLANs can be blocked using
- private interfaces (or a firewall):</para>
+ <para>Any communication between the <acronym>VLAN</acronym>s
+ can be blocked using a firewall or, as seen in this example,
+ private interfaces:</para>
<screen>&prompt.root; <userinput>ifconfig bridge0 private vlan100 private vlan101</userinput></screen>
- <para>The customers are completely isolated from each other,
- the full <hostid role="netmask">/24</hostid> address range
- can be allocated without subnetting.</para>
+ <para>The customers are completely isolated from each other
+ and the full <hostid role="netmask">/24</hostid> address
+ range can be allocated without subnetting.</para>
</sect3>
<sect3>
<title>Address Limits</title>
- <para>The number of unique source MAC addresses behind an
- interface can be limited. Once the limit is reached packets
- with unknown source addresses are dropped until an
- existing host cache entry expires or is removed.</para>
+ <para>The number of unique source <acronym>MAC</acronym>
+ addresses behind an interface can be limited. Once the
+ limit is reached, packets with unknown source addresses
+ are dropped until an existing host cache entry expires or
+ is removed.</para>
<para>The following example sets the maximum number of
- Ethernet devices for
- <hostid role="hostname">CustomerA</hostid> on
- <literal>vlan100</literal> to 10.</para>
+ Ethernet devices for <hostid
+ role="hostname">CustomerA</hostid> on
+ <literal>vlan100</literal> to 10:</para>
<screen>&prompt.root; <userinput>ifconfig bridge0 ifmaxaddr vlan100 10</userinput></screen>
</sect3>
<sect3>
- <title>SNMP Monitoring</title>
-
- <para>The bridge interface and STP parameters can be monitored
- via the SNMP daemon which is included in the &os; base
- system. The exported bridge MIBs conform to the IETF
- standards so any SNMP client or monitoring package can be
+ <title><acronym>SNMP</acronym> Monitoring</title>
+
+ <para>The bridge interface and <acronym>STP</acronym>
+ parameters can be monitored via &man.bsnmpd.1; which is
+ included in the &os; base system. The exported bridge
+ <acronym>MIB</acronym>s conform to the
+ <acronym>IETF</acronym> standards so any
+ <acronym>SNMP</acronym> client or monitoring package can be
used to retrieve the data.</para>
- <para>On the bridge machine uncomment the
+ <para>On the bridge, uncomment the
<literal>begemotSnmpdModulePath."bridge" =
"/usr/lib/snmp_bridge.so"</literal> line from
- <filename>/etc/snmp.config</filename> and start the
- <application>bsnmpd</application> daemon. Other
- configuration such as community names and access lists may
- need to be modified. See &man.bsnmpd.1; and
- &man.snmp.bridge.3; for more information.</para>
+ <filename>/etc/snmp.config</filename> and start
+ &man.bsnmpd.1;. Other configuration, such as community
+ names and access lists, may need to be modified. See
+ &man.bsnmpd.1; and &man.snmp.bridge.3; for more
+ information.</para>
<para>The following examples use the
- <application>Net-SNMP</application> software
- (<filename role="package">net-mgmt/net-snmp</filename>) to
- query a bridge, the
- <filename role="package">net-mgmt/bsnmptools</filename> port
- can also be used. From the SNMP client host add to
- <filename>$HOME/.snmp/snmp.conf</filename> the following
- lines to import the bridge MIB definitions in to
- <application>Net-SNMP</application>:</para>
+ <application>Net-SNMP</application> software (<filename
+ role="package">net-mgmt/net-snmp</filename>) to query a
+ bridge from a client system. The <filename
+ role="package">net-mgmt/bsnmptools</filename> port can
+ also be used. From the <acronym>SNMP</acronym> client
+ which is running <application>Net-SNMP</application>, add
+ the following lines to
+ <filename>$HOME/.snmp/snmp.conf</filename> in order to
+ import the bridge <acronym>MIB</acronym> definitions:</para>
<programlisting>mibdirs +/usr/share/snmp/mibs
mibs +BRIDGE-MIB:RSTP-MIB:BEGEMOT-MIB:BEGEMOT-BRIDGE-MIB</programlisting>
- <para>To monitor a single bridge via the IETF BRIDGE-MIB
- (RFC4188) do</para>
+ <para>To monitor a single bridge using the IETF BRIDGE-MIB
+ (RFC4188):</para>
<screen>&prompt.user; <userinput>snmpwalk -v 2c -c public bridge1.example.com mib-2.dot1dBridge</userinput>
BRIDGE-MIB::dot1dBaseBridgeAddress.0 = STRING: 66:fb:9b:6e:5c:44
@@ -3254,16 +3333,16 @@ BRIDGE-MIB::dot1dStpPortDesignatedPort.3 = Hex-STRING: 03 80
BRIDGE-MIB::dot1dStpPortForwardTransitions.3 = Counter32: 1
RSTP-MIB::dot1dStpVersion.0 = INTEGER: rstp(2)</screen>
- <para>The <literal>dot1dStpTopChanges.0</literal> value is two
- which means that the STP bridge topology has changed twice,
- a topology change means that one or more links in the
- network have changed or failed and a new tree has been
- calculated. The
+ <para>The <literal>dot1dStpTopChanges.0</literal> value is
+ two, indicating that the <acronym>STP</acronym> bridge
+ topology has changed twice. A topology change means that
+ one or more links in the network have changed or failed
+ and a new tree has been calculated. The
<literal>dot1dStpTimeSinceTopologyChange.0</literal> value
will show when this happened.</para>
- <para>To monitor multiple bridge interfaces one may use the
- private BEGEMOT-BRIDGE-MIB:</para>
+ <para>To monitor multiple bridge interfaces, the private
+ BEGEMOT-BRIDGE-MIB can be used:</para>
<screen>&prompt.user; <userinput>snmpwalk -v 2c -c public bridge1.example.com</userinput>
enterprises.fokus.begemot.begemotBridge
@@ -3282,7 +3361,7 @@ BEGEMOT-BRIDGE-MIB::begemotBridgeStpDesignatedRoot."bridge0" = Hex-STRING: 80 00
BEGEMOT-BRIDGE-MIB::begemotBridgeStpDesignatedRoot."bridge2" = Hex-STRING: 80 00 00 50 8B B8 C6 A9</screen>
<para>To change the bridge interface being monitored via the
- <literal>mib-2.dot1dBridge</literal> subtree do:</para>
+ <literal>mib-2.dot1dBridge</literal> subtree:</para>
<screen>&prompt.user; <userinput>snmpset -v 2c -c private bridge1.example.com</userinput>
BEGEMOT-BRIDGE-MIB::begemotBridgeDefaultBridgeIf.0 s bridge2</screen>
@@ -3304,8 +3383,8 @@ BEGEMOT-BRIDGE-MIB::begemotBridgeDefaultBridgeIf.0 s bridge2</screen>
<indexterm><primary>lagg</primary></indexterm>
<indexterm><primary>failover</primary></indexterm>
- <indexterm><primary>fec</primary></indexterm>
- <indexterm><primary>lacp</primary></indexterm>
+ <indexterm><primary><acronym>FEC</acronym></primary></indexterm>
+ <indexterm><primary><acronym>LACP</acronym></primary></indexterm>
<indexterm><primary>loadbalance</primary></indexterm>
<indexterm><primary>roundrobin</primary></indexterm>
@@ -3320,6 +3399,9 @@ BEGEMOT-BRIDGE-MIB::begemotBridgeDefaultBridgeIf.0 s bridge2</screen>
<sect2>
<title>Operating Modes</title>
+ <para>The following operating modes are supported by
+ &man.lagg.4;:</para>
+
<variablelist>
<varlistentry>
<term>Failover</term>
@@ -3327,8 +3409,8 @@ BEGEMOT-BRIDGE-MIB::begemotBridgeDefaultBridgeIf.0 s bridge2</screen>
<para>Sends and receives traffic only through the master
port. If the master port becomes unavailable, the next
active port is used. The first interface added is the
- master port; any interfaces added after that are used as
- failover devices. If failover to a non-master port
+ master port and any interfaces added after that are used
+ as failover devices. If failover to a non-master port
occurs, the original port will become master when it
becomes available again.</para>
</listitem>
@@ -3337,40 +3419,49 @@ BEGEMOT-BRIDGE-MIB::begemotBridgeDefaultBridgeIf.0 s bridge2</screen>
<varlistentry>
<term>&cisco; Fast &etherchannel;</term>
<listitem>
- <para>&cisco; Fast &etherchannel; (FEC), is a static setup
- and does not negotiate aggregation with the peer or
- exchange frames to monitor the link. If the switch
- supports LACP then that should be used instead.</para>
+ <para>&cisco; Fast &etherchannel; (<acronym>FEC</acronym>)
+ is a static setup and does not negotiate aggregation
+ with the peer or exchange frames to monitor the link.
+ If the switch supports <acronym>LACP</acronym>, that
+ should be used instead.</para>
<para><acronym>FEC</acronym> balances outgoing traffic
across the active ports based on hashed protocol header
information and accepts incoming traffic from any active
port. The hash includes the Ethernet source and
- destination address, and, if available, the VLAN tag,
- and the IPv4/IPv6 source and destination address.</para>
+ destination address and, if available, the
+ <acronym>VLAN</acronym> tag, and the
+ <acronym>IPv4</acronym> or <acronym>IPv6</acronym>
+ source and destination address.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>LACP</term>
+ <term><acronym>LACP</acronym></term>
<listitem>
<para>The &ieee; 802.3ad Link Aggregation Control Protocol
- (LACP) and the Marker Protocol. LACP will negotiate a
- set of aggregable links with the peer in to one or more
- Link Aggregated Groups (LAG). Each LAG is composed of
- ports of the same speed, set to full-duplex operation.
- The traffic will be balanced across the ports in the LAG
- with the greatest total speed, in most cases there will
- only be one LAG which contains all ports. In the event
- of changes in physical connectivity, Link Aggregation
- will quickly converge to a new configuration.</para>
+ (<acronym>LACP</acronym>) and the Marker Protocol.
+ <acronym>LACP</acronym> will negotiate a set of
+ aggregable links with the peer in to one or more Link
+ Aggregated Groups (<acronym>LAG</acronym>s). Each
+ <acronym>LAG</acronym> is composed of ports of the
+ same speed, set to full-duplex operation. The traffic
+ will be balanced across the ports in the
+ <acronym>LAG</acronym> with the greatest total speed.
+ In most cases, there will only be one
+ <acronym>LAG</acronym> which contains all ports. In
+ the event of changes in physical connectivity,
+ <acronym>LACP</acronym> will quickly converge to a new
+ configuration.</para>
<para><acronym>LACP</acronym> balances outgoing traffic
across the active ports based on hashed protocol header
information and accepts incoming traffic from any active
port. The hash includes the Ethernet source and
- destination address, and, if available, the VLAN tag,
- and the IPv4/IPv6 source and destination address.</para>
+ destination address and, if available, the
+ <acronym>VLAN</acronym> tag, and the IPv4 or
+ <acronym>IPv6</acronym> source and destination
+ address.</para>
</listitem>
</varlistentry>
@@ -3388,7 +3479,7 @@ BEGEMOT-BRIDGE-MIB::begemotBridgeDefaultBridgeIf.0 s bridge2</screen>
<para>Distributes outgoing traffic using a round-robin
scheduler through all active ports and accepts incoming
traffic from any active port. This mode violates
- Ethernet Frame ordering and should be used with
+ Ethernet frame ordering and should be used with
caution.</para>
</listitem>
</varlistentry>
@@ -3399,23 +3490,24 @@ BEGEMOT-BRIDGE-MIB::begemotBridgeDefaultBridgeIf.0 s bridge2</screen>
<title>Examples</title>
<example id="networking-lacp-aggregation-cisco">
- <title>LACP Aggregation with a &cisco; Switch</title>
+ <title><acronym>LACP</acronym> Aggregation with a &cisco;
+ Switch</title>
<para>This example connects two interfaces on a &os; machine
to the switch as a single load balanced and fault tolerant
link. More interfaces can be added to increase throughput
- and fault tolerance. Since frame ordering is mandatory on
- Ethernet links then any traffic between two stations always
- flows over the same physical link limiting the maximum speed
- to that of one interface. The transmit algorithm attempts
- to use as much information as it can to distinguish
- different traffic flows and balance across the available
- interfaces.</para>
-
- <para>On the &cisco; switch add the
+ and fault tolerance. Frame ordering is mandatory on
+ Ethernet links and any traffic between two stations always
+ flows over the same physical link, limiting the maximum
+ speed to that of one interface. The transmit algorithm
+ attempts to use as much information as it can to
+ distinguish different traffic flows and balance across the
+ available interfaces.</para>
+
+ <para>On the &cisco; switch, add the
<replaceable>FastEthernet0/1</replaceable> and
- <replaceable>FastEthernet0/2</replaceable> interfaces to the
- channel-group <replaceable>1</replaceable>:</para>
+ <replaceable>FastEthernet0/2</replaceable> interfaces to
+ channel group <replaceable>1</replaceable>:</para>
<screen><userinput>interface <replaceable>FastEthernet0/1</replaceable>
channel-group <replaceable>1</replaceable> mode active
@@ -3428,7 +3520,7 @@ BEGEMOT-BRIDGE-MIB::begemotBridgeDefaultBridgeIf.0 s bridge2</screen>
<para>Create the &man.lagg.4; interface using
<replaceable>fxp0</replaceable> and
<replaceable>fxp1</replaceable>, and bring the interfaces up
- with the IP Address of
+ with the <acronym>IP</acronym> address of
<replaceable>10.0.0.3/24</replaceable>:</para>
<screen>&prompt.root; <userinput>ifconfig <replaceable>fxp0</replaceable> up</userinput>
@@ -3442,9 +3534,10 @@ BEGEMOT-BRIDGE-MIB::begemotBridgeDefaultBridgeIf.0 s bridge2</screen>
<para>Ports marked as <emphasis>ACTIVE</emphasis> are part of
the active aggregation group that has been negotiated with
- the remote switch and traffic will be transmitted and
- received. Use the verbose output of &man.ifconfig.8; to
- view the LAG identifiers.</para>
+ the remote switch. Traffic will be transmitted and
+ received through active ports. Use the verbose output of
+ &man.ifconfig.8; to view the <acronym>LAG</acronym>
+ identifiers.</para>
<screen>lagg0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
options=8&lt;VLAN_MTU&gt;
@@ -3455,7 +3548,7 @@ BEGEMOT-BRIDGE-MIB::begemotBridgeDefaultBridgeIf.0 s bridge2</screen>
laggport: fxp1 flags=1c&lt;ACTIVE,COLLECTING,DISTRIBUTING&gt;
laggport: fxp0 flags=1c&lt;ACTIVE,COLLECTING,DISTRIBUTING&gt;</screen>
- <para>To see the port status on the switch, use
+ <para>To see the port status on the &cisco; switch, use
<userinput>show lacp neighbor</userinput>:</para>
<screen>switch# show lacp neighbor
@@ -3472,8 +3565,8 @@ Port Flags Priority Dev ID Age Key Number State
Fa0/1 SA 32768 0005.5d71.8db8 29s 0x146 0x3 0x3D
Fa0/2 SA 32768 0005.5d71.8db8 29s 0x146 0x4 0x3D</screen>
- <para>For more detail use the <userinput>show lacp neighbor
- detail</userinput> command.</para>
+ <para>For more detail, type <userinput>show lacp neighbor
+ detail</userinput>.</para>
<para>To retain this configuration across reboots, the
following entries can be added to
@@ -3490,11 +3583,12 @@ ifconfig_<literal>lagg<replaceable>0</replaceable></literal>="laggproto lacp lag
<para>Failover mode can be used to switch over to a secondary
interface if the link is lost on the master interface.
- Bring the underlying physical interfaces up. Create the
- &man.lagg.4; interface, using
- <replaceable>fxp0</replaceable> as the master interface and
- <replaceable>fxp1</replaceable> as the secondary interface
- and assign an IP Address of
+ To configure failover mode, first bring the underlying
+ physical interfaces up. Then, create the &man.lagg.4;
+ interface, using <replaceable>fxp0</replaceable> as the
+ master interface and <replaceable>fxp1</replaceable> as
+ the secondary interface, and assign an <acronym>IP</acronym>
+ address of
<replaceable>10.0.0.15/24</replaceable>:</para>
<screen>&prompt.root; <userinput>ifconfig <replaceable>fxp0</replaceable> up</userinput>
@@ -3502,9 +3596,8 @@ ifconfig_<literal>lagg<replaceable>0</replaceable></literal>="laggproto lacp lag
&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> create</userinput>
&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> up laggproto failover laggport <replaceable>fxp0</replaceable> laggport <replaceable>fxp1</replaceable> <replaceable>10.0.0.15/24</replaceable></userinput></screen>
- <para>The interface will look something like this, the major
- differences will be the <acronym>MAC</acronym> address and
- the device names:</para>
+ <para>The interface should now look something like
+ this:</para>
<screen>&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal></userinput>
lagg0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
@@ -3519,9 +3612,9 @@ lagg0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 150
<para>Traffic will be transmitted and received on
<replaceable>fxp0</replaceable>. If the link is lost on
- <replaceable>fxp0</replaceable> then
+ <replaceable>fxp0</replaceable>,
<replaceable>fxp1</replaceable> will become the active link.
- If the link is restored on the master interface then it will
+ If the link is restored on the master interface, it will
once again become the active link.</para>
<para>To retain this configuration across reboots, the
@@ -3538,28 +3631,29 @@ ifconfig_<literal>lagg<replaceable>0</replaceable></literal>="laggproto failover
<title>Failover Mode Between Wired and Wireless
Interfaces</title>
- <para>For laptop users, it is usually desirable to make
- wireless as a secondary interface, which is to be used when
- the wired connection is not available. With &man.lagg.4;,
- it is possible to use one IP address, prefer the wired
- connection for both performance and security reasons, while
+ <para>For laptop users, it is usually desirable to configure
+ the wireless device as a secondary interface, which is used
+ when the wired connection is not available. With
+ &man.lagg.4;, it is possible to use one
+ <acronym>IP</acronym> address, prefer the wired connection
+ for both performance and security reasons, while
maintaining the ability to transfer data over the wireless
connection.</para>
- <para>In this setup, we will need to override the underlying
- wireless interface's <acronym>MAC</acronym> address to match
- the &man.lagg.4;'s, which is inherited from the master
- interface being used, the wired interface.</para>
-
- <para>In this setup, we will treat the wired interface,
- <replaceable>bge0</replaceable>, as the master, and the
- wireless interface, <replaceable>wlan0</replaceable>, as the
- failover interface. The <replaceable>wlan0</replaceable>
- was created from <replaceable>iwn0</replaceable> which we
- will set up with the wired connection's
- <acronym>MAC</acronym> address. The first step would be to
- obtain the <acronym>MAC</acronym> address from the wired
- interface:</para>
+ <para>In this setup, override the underlying wireless
+ interface's <acronym>MAC</acronym> address to match that
+ of the &man.lagg.4;, which is inherited from the wired
+ interface.</para>
+
+ <para>In this example, the wired interface,
+ <replaceable>bge0</replaceable>, is the master, and the
+ wireless interface, <replaceable>wlan0</replaceable>, is
+ the failover interface. The
+ <replaceable>wlan0</replaceable> device was created from
+ <replaceable>iwn0</replaceable>, which will be configured
+ with the wired connection's <acronym>MAC</acronym> address.
+ The first step is to determine the <acronym>MAC</acronym>
+ address of the wired interface:</para>
<screen>&prompt.root; <userinput>ifconfig <replaceable>bge0</replaceable></userinput>
bge0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
@@ -3570,32 +3664,30 @@ bge0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
media: Ethernet autoselect (1000baseT &lt;full-duplex&gt;)
status: active</screen>
- <para>You can replace the <replaceable>bge0</replaceable> to
- match your reality, and will get a different
- <literal>ether</literal> line which is the
- <acronym>MAC</acronym> address of your wired interface.
- Now, we change the underlying wireless interface,
- <replaceable>iwn0</replaceable>:</para>
+ <para>Replace <replaceable>bge0</replaceable> to match the
+ system's interface name. The <literal>ether</literal>
+ line will contain the <acronym>MAC</acronym> address of
+ the wired interface. Now, change the
+ <acronym>MAC</acronym> address of the underlying wireless
+ interface:</para>
<screen>&prompt.root; <userinput>ifconfig <replaceable>iwn0</replaceable> ether <replaceable>00:21:70:da:ae:37</replaceable></userinput></screen>
- <para>Bring the wireless interface up, but do not set an IP
- address on it:</para>
+ <para>Bring the wireless interface up, but do not set an
+ <acronym>IP</acronym> address:</para>
<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>iwn0</replaceable> ssid <replaceable>my_router</replaceable> up</userinput></screen>
<para>Bring the <replaceable>bge0</replaceable> interface up.
Create the &man.lagg.4; interface with
<replaceable>bge0</replaceable> as master, and failover to
- <replaceable>wlan0</replaceable> if necessary:</para>
+ <replaceable>wlan0</replaceable>:</para>
<screen>&prompt.root; <userinput>ifconfig <replaceable>bge0</replaceable> up</userinput>
&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> create</userinput>
&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> up laggproto failover laggport <replaceable>bge0</replaceable> laggport <replaceable>wlan0</replaceable></userinput></screen>
- <para>The interface will look something like this, the major
- differences will be the <acronym>MAC</acronym> address and
- the device names:</para>
+ <para>The interface will now look something like this:</para>
<screen>&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal></userinput>
lagg0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
@@ -3607,8 +3699,8 @@ lagg0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 150
laggport: wlan0 flags=0&lt;&gt;
laggport: bge0 flags=5&lt;MASTER,ACTIVE&gt;</screen>
- <para>Then start the DHCP client to obtain an IP
- address:</para>
+ <para>Then, start the <acronym>DHCP</acronym> client to
+ obtain an <acronym>IP</acronym> address:</para>
<screen>&prompt.root; <userinput>dhclient <literal>lagg<replaceable>0</replaceable></literal></userinput></screen>
@@ -3648,100 +3740,62 @@ ifconfig_<literal>lagg<replaceable>0</replaceable></literal>="laggproto failover
<indexterm><primary>diskless workstation</primary></indexterm>
<indexterm><primary>diskless operation</primary></indexterm>
- <para>A FreeBSD machine can boot over the network and operate
+ <para>A &os; machine can boot over the network and operate
without a local disk, using file systems mounted from an
<acronym>NFS</acronym> server. No system modification is
necessary, beyond standard configuration files. Such a system
is relatively easy to set up because all the necessary elements
are readily available:</para>
- <itemizedlist>
- <listitem>
- <para>There are at least two possible methods to load the
- kernel over the network:</para>
-
- <itemizedlist>
- <listitem>
- <para><acronym>PXE</acronym>: The &intel; Preboot
- eXecution Environment system is a form of smart boot ROM
- built into some networking cards or motherboards. See
- &man.pxeboot.8; for more details.</para>
- </listitem>
-
- <listitem>
- <para>The <application>Etherboot</application> port
- (<filename role="package">net/etherboot</filename>)
- produces ROM-able code to boot kernels over the network.
- The code can be either burnt into a boot PROM on a
- network card, or loaded from a local floppy (or hard)
- disk drive, or from a running &ms-dos; system. Many
- network cards are supported.</para>
- </listitem>
- </itemizedlist>
- </listitem>
+ <para>The &intel; Preboot eXecution Environment
+ (<acronym>PXE</acronym>) can be used to load the kernel over
+ the network. It provides a form of smart boot
+ <acronym>ROM</acronym> built into some networking cards or
+ motherboards. See &man.pxeboot.8; for more details.</para>
- <listitem>
- <para>A sample script
- (<filename>/usr/share/examples/diskless/clone_root</filename>)
- eases the creation and maintenance of the workstation's root
- file system on the server. The script will probably require
- a little customization but it will get you started very
- quickly.</para>
- </listitem>
+ <para>A sample script
+ (<filename>/usr/share/examples/diskless/clone_root</filename>)
+ eases the creation and maintenance of the workstation's root
+ file system on the server. The script will probably require
+ a little customization.</para>
- <listitem>
- <para>Standard system startup files exist
- in <filename class="directory">/etc</filename>
- to detect and support a diskless system startup.</para>
- </listitem>
+ <para>Standard system startup files exist in <filename
+ class="directory">/etc</filename> to detect and support a
+ diskless system startup.</para>
- <listitem>
- <para>Swapping, if needed, can be done either to an
- <acronym>NFS</acronym> file or to a local disk.</para>
- </listitem>
- </itemizedlist>
+ <para>Swapping, if needed, can be done either to an
+ <acronym>NFS</acronym> file or to a local disk.</para>
<para>There are many ways to set up diskless workstations. Many
elements are involved, and most can be customized to suit local
taste. The following will describe variations on the setup of a
complete system, emphasizing simplicity and compatibility with
- the standard FreeBSD startup scripts. The system described has
+ the standard &os; startup scripts. The system described has
the following characteristics:</para>
<itemizedlist>
<listitem>
- <para>The diskless workstations use a shared read-only
- <filename class="directory">/</filename> file system,
- and a shared read-only
+ <para>The diskless workstations use a shared, read-only
+ <filename class="directory">/</filename> and
<filename class="directory">/usr</filename>.</para>
- <para>The root file system is a copy of a standard FreeBSD
- root (typically the server's), with some configuration files
- overridden by ones specific to diskless operation or,
- possibly, to the workstation they belong to.</para>
+ <para>The root file system is a copy of a standard &os;
+ root, with some configuration files overridden by ones
+ specific to diskless operation or, possibly, to the
+ workstation they belong to.</para>
<para>The parts of the root which have to be writable are
overlaid with &man.md.4; file systems. Any changes will be
lost when the system reboots.</para>
</listitem>
-
- <listitem>
- <para>The kernel is transferred and loaded either with
- <application>Etherboot</application> or
- <acronym>PXE</acronym> as some situations may mandate the
- use of either method.</para>
- </listitem>
</itemizedlist>
<caution>
<para>As described, this system is insecure. It should live in
- a protected area of a network, and be untrusted by other
+ a protected area of a network and be untrusted by other
hosts.</para>
</caution>
- <para>All the information in this section has been tested using
- &os; 5.2.1-RELEASE.</para>
-
<sect2>
<title>Background Information</title>
@@ -3763,8 +3817,8 @@ ifconfig_<literal>lagg<replaceable>0</replaceable></literal>="laggproto failover
</itemizedlist>
<para>In this context, having some knowledge of the background
- mechanisms involved is very useful to solve the problems that
- may arise.</para>
+ mechanisms involved is useful to solve the problems that may
+ arise.</para>
<para>Several operations need to be performed for a successful
bootstrap:</para>
@@ -3772,26 +3826,26 @@ ifconfig_<literal>lagg<replaceable>0</replaceable></literal>="laggproto failover
<itemizedlist>
<listitem>
<para>The machine needs to obtain initial parameters such as
- its IP address, executable filename, server name, root
- path. This is done using the <acronym>DHCP</acronym> or
- BOOTP protocols. <acronym>DHCP</acronym> is a compatible
- extension of BOOTP, and uses the same port numbers and
- basic packet format.</para>
-
- <para>It is possible to configure a system to use only
- BOOTP. The &man.bootpd.8; server program is included in
- the base &os; system.</para>
-
- <para>However, <acronym>DHCP</acronym> has a number of
- advantages over BOOTP (nicer configuration files,
- possibility of using <acronym>PXE</acronym>, plus many
- others not directly related to diskless operation), and we
- will describe mainly a <acronym>DHCP</acronym>
+ its <acronym>IP</acronym> address, executable filename,
+ server name, and root path. This is done using the
+ <acronym>DHCP</acronym> or <acronym>BOOTP</acronym>
+ protocols. <acronym>DHCP</acronym> is a compatible
+ extension of <acronym>BOOTP</acronym>, and uses the same
+ port numbers and basic packet format. It is possible to
+ configure a system to use only <acronym>BOOTP</acronym>
+ and &man.bootpd.8; is included in the base &os;
+ system.</para>
+ </listitem>
+
+ <listitem>
+ <para><acronym>DHCP</acronym> has a number of advantages
+ over <acronym>BOOTP</acronym> such as nicer configuration
+ files and support for <acronym>PXE</acronym>. This
+ section describes mainly a <acronym>DHCP</acronym>
configuration, with equivalent examples using
&man.bootpd.8; when possible. The sample configuration
- will use the <application>ISC DHCP</application> software
- package (release 3.0.1.r12 was installed on the test
- server).</para>
+ uses <application>ISC DHCP</application> which is
+ available in the Ports Collection.</para>
</listitem>
<listitem>
@@ -3800,56 +3854,32 @@ ifconfig_<literal>lagg<replaceable>0</replaceable></literal>="laggproto failover
<acronym>NFS</acronym> are used. The choice between
<acronym>TFTP</acronym> and <acronym>NFS</acronym> is a
compile time option in several places. A common source of
- error is to specify filenames for the wrong protocol:
+ error is to specify filenames for the wrong protocol.
<acronym>TFTP</acronym> typically transfers all files from
- a single directory on the server, and would expect
- filenames relative to this directory.
- <acronym>NFS</acronym> needs absolute file paths.</para>
+ a single directory on the server and expects filenames
+ relative to this directory. <acronym>NFS</acronym> needs
+ absolute file paths.</para>
</listitem>
<listitem>
<para>The possible intermediate bootstrap programs and the
- kernel need to be initialized and executed. There are
- several important variations in this area:</para>
-
- <itemizedlist>
- <listitem>
-
- <para><acronym>PXE</acronym> will load &man.pxeboot.8;,
- which is a modified version of the &os; third stage
- loader. The &man.loader.8; will obtain most
- parameters necessary to system startup, and leave them
- in the kernel environment before transferring control.
- It is possible to use a <filename>GENERIC</filename>
- kernel in this case.</para>
- </listitem>
-
- <listitem>
- <para><application>Etherboot</application>, will
- directly load the kernel, with less preparation. You
- will need to build a kernel with specific
- options.</para>
- </listitem>
- </itemizedlist>
-
- <para><acronym>PXE</acronym> and
- <application>Etherboot</application> work equally well;
- however, because kernels normally let the &man.loader.8;
- do more work for them, <acronym>PXE</acronym> is the
- preferred method.</para>
-
- <para>If your <acronym>BIOS</acronym> and network cards
- support <acronym>PXE</acronym>, you should probably use
- it.</para>
+ kernel need to be initialized and executed.
+ <acronym>PXE</acronym> loads &man.pxeboot.8;, which is
+ a modified version of the &os; third stage loader,
+ &man.loader.8;. The third stage loader will obtain most
+ parameters necessary to system startup and leave them
+ in the kernel environment before transferring control.
+ It is possible to use a <filename>GENERIC</filename>
+ kernel in this case.</para>
</listitem>
<listitem>
- <para>Finally, the machine needs to access its file systems.
- <acronym>NFS</acronym> is used in all cases.</para>
+ <para>Finally, the machine needs to access its file systems
+ using <acronym>NFS</acronym>.</para>
</listitem>
</itemizedlist>
- <para>See also &man.diskless.8; manual page.</para>
+ <para>Refer to &man.diskless.8; for more information.</para>
</sect2>
<sect2>
@@ -3865,22 +3895,19 @@ ifconfig_<literal>lagg<replaceable>0</replaceable></literal>="laggproto failover
</indexterm>
<para>The <application>ISC DHCP</application> server can
- answer both BOOTP and <acronym>DHCP</acronym>
- requests.</para>
+ answer both <acronym>BOOTP</acronym> and
+ <acronym>DHCP</acronym> requests.</para>
- <para><application>ISC DHCP 4.2</application> is not part of
- the base system. You will first need to install the
- <filename role="package">net/isc-dhcp42-server</filename>
- port or the corresponding package.</para>
+ <para><application>ISC DHCP</application> is not part of
+ the base system. Install the <filename
+ role="package">net/isc-dhcp42-server</filename> port or
+ package.</para>
<para>Once <application>ISC DHCP</application> is installed,
- it needs a configuration file to run (normally named
- <filename>/usr/local/etc/dhcpd.conf</filename>). Here
- follows a commented example, where host
- <hostid>margaux</hostid> uses
- <application>Etherboot</application> and host
- <hostid>corbieres</hostid> uses
- <acronym>PXE</acronym>:</para>
+ edit its configuration file,
+ <filename>/usr/local/etc/dhcpd.conf</filename>. Here
+ follows a commented example for <acronym>PXE</acronym> host
+ <hostid>corbieres</hostid>:</para>
<programlisting>default-lease-time 600;
max-lease-time 7200;
@@ -3895,19 +3922,12 @@ subnet 192.168.4.0 netmask 255.255.255.0 {
option subnet-mask 255.255.255.0;
option broadcast-address 192.168.4.255;
- host margaux {
- hardware ethernet 01:23:45:67:89:ab;
- fixed-address margaux.example.com;
- next-server 192.168.4.4; <co id="co-dhcp-next-server"/>
- filename "/data/misc/kernel.diskless"; <co id="co-dhcp-filename"/>
- option root-path "192.168.4.4:/data/misc/diskless"; <co id="co-dhcp-root-path"/>
- }
host corbieres {
hardware ethernet 00:02:b3:27:62:df;
fixed-address corbieres.example.com;
- next-server 192.168.4.4;
- filename "pxeboot";
- option root-path "192.168.4.4:/data/misc/diskless";
+ next-server 192.168.4.4; <co id="co-dhcp-next-server"/>
+ filename "pxeboot"; <co id="co-dhcp-filename"/>
+ option root-path "192.168.4.4:/data/misc/diskless"; <co id="co-dhcp-root-path"/>
}
}</programlisting>
@@ -3917,42 +3937,35 @@ subnet 192.168.4.0 netmask 255.255.255.0 {
to send the value in the <literal>host</literal>
declarations as the hostname for the diskless host.
An alternate way would be to add an <literal>option
- host-name
- <replaceable>margaux</replaceable></literal> inside
- the <literal>host</literal> declarations.</para>
+ host-name <replaceable>corbieres</replaceable></literal>
+ inside the <literal>host</literal> declarations.</para>
</callout>
<callout arearefs="co-dhcp-next-server">
<para>The <literal>next-server</literal> directive
designates the <acronym>TFTP</acronym> or
<acronym>NFS</acronym> server to use for loading
- loader or kernel file (the default is to use the same
- host as the <acronym>DHCP</acronym> server).</para>
+ &man.loader.8; or the kernel file. The default is to
+ use the same host as the <acronym>DHCP</acronym>
+ server.</para>
</callout>
<callout arearefs="co-dhcp-filename">
- <para>The <literal>filename</literal> directive
- defines the file that
- <application>Etherboot</application> or
- <acronym>PXE</acronym> will load for the next execution
- step. It must be specified according to the transfer
- method used. <application>Etherboot</application> can
- be compiled to use <acronym>NFS</acronym> or
- <acronym>TFTP</acronym>. The &os; port configures
- <acronym>NFS</acronym> by default.
+ <para>The <literal>filename</literal> directive defines
+ the file that <acronym>PXE</acronym> will load for the
+ next execution step. It must be specified according
+ to the transfer method used.
<acronym>PXE</acronym> uses <acronym>TFTP</acronym>,
- which is why a relative filename is used here (this may
- depend on the <acronym>TFTP</acronym> server
- configuration, but would be fairly typical). Also,
+ which is why a relative filename is used here. Also,
<acronym>PXE</acronym> loads
<filename>pxeboot</filename>, not the kernel. There are
other interesting possibilities, like loading
<filename>pxeboot</filename> from a &os; CD-ROM
- <filename class="directory">/boot</filename> directory
- (as &man.pxeboot.8; can load a
- <filename>GENERIC</filename> kernel, this makes it
- possible to use <acronym>PXE</acronym> to boot from a
- remote CD-ROM).</para>
+ <filename class="directory">/boot</filename> directory.
+ Since &man.pxeboot.8; can load a
+ <filename>GENERIC</filename> kernel, it is possible to
+ use <acronym>PXE</acronym> to boot from a remote
+ CD-ROM.</para>
</callout>
<callout arearefs="co-dhcp-root-path">
@@ -3960,101 +3973,19 @@ subnet 192.168.4.0 netmask 255.255.255.0 {
the path to the root file system, in usual
<acronym>NFS</acronym> notation. When using
<acronym>PXE</acronym>, it is possible to leave off the
- host's IP as long as you do not enable the kernel option
- BOOTP. The <acronym>NFS</acronym> server will then be
- the same as the <acronym>TFTP</acronym> one.</para>
+ host's <acronym>IP</acronym> address as long as the
+ <acronym>BOOTP</acronym> kernel option is not enabled.
+ The <acronym>NFS</acronym> server will then be the
+ same as the <acronym>TFTP</acronym> one.</para>
</callout>
</calloutlist>
</sect3>
<sect3>
- <title>Configuration Using BOOTP</title>
-
- <indexterm>
- <primary>BOOTP</primary>
- <secondary>diskless operation</secondary>
- </indexterm>
-
- <para>Here follows an equivalent
- <application>bootpd</application> configuration (reduced to
- one client). This would be found in
- <filename>/etc/bootptab</filename>.</para>
-
- <para>Please note that <application>Etherboot</application>
- must be compiled with the non-default option
- <literal>NO_DHCP_SUPPORT</literal> in order to use BOOTP,
- and that <acronym>PXE</acronym> <emphasis>needs</emphasis>
- <acronym>DHCP</acronym>. The only obvious advantage of
- <application>bootpd</application> is that it exists in the
- base system.</para>
-
- <programlisting>.def100:\
- :hn:ht=1:sa=192.168.4.4:vm=rfc1048:\
- :sm=255.255.255.0:\
- :ds=192.168.4.1:\
- :gw=192.168.4.1:\
- :hd="/tftpboot":\
- :bf="/kernel.diskless":\
- :rp="192.168.4.4:/data/misc/diskless":
-
-margaux:ha=0123456789ab:tc=.def100</programlisting>
- </sect3>
-
- <sect3>
- <title>Preparing a Boot Program with
- <application>Etherboot</application></title>
-
- <indexterm>
- <primary>Etherboot</primary>
- </indexterm>
-
- <para><ulink
- url="http://etherboot.sourceforge.net">Etherboot's Web
- site</ulink> contains <ulink
- url="http://etherboot.sourceforge.net/doc/html/userman/t1.html">
- extensive documentation</ulink> mainly intended for Linux
- systems, but nonetheless containing useful information. The
- following will just outline how you would use
- <application>Etherboot</application> on a FreeBSD
- system.</para>
-
- <para>You must first install the
- <filename role="package">net/etherboot</filename> package or
- port.</para>
-
- <para>You can change the <application>Etherboot</application>
- configuration (i.e., to use <acronym>TFTP</acronym> instead
- of <acronym>NFS</acronym>) by editing the
- <filename>Config</filename> file in the
- <application>Etherboot</application> source
- directory.</para>
-
- <para>For our setup, we shall use a boot floppy. For other
- methods (PROM, or &ms-dos; program), please refer to the
- <application>Etherboot</application> documentation.</para>
-
- <para>To make a boot floppy, insert a floppy in the drive on
- the machine where you installed
- <application>Etherboot</application>, then change your
- current directory to
- the <filename class="directory">src</filename>
- directory in the <application>Etherboot</application> tree and
- type:</para>
-
- <screen>&prompt.root; <userinput>gmake bin32/<replaceable>devicetype</replaceable>.fd0</userinput></screen>
-
- <para><replaceable>devicetype</replaceable> depends on the
- type of the Ethernet card in the diskless workstation.
- Refer to the <filename>NIC</filename> file in the same
- directory to determine the right
- <replaceable>devicetype</replaceable>.</para>
- </sect3>
-
- <sect3>
<title>Booting with <acronym>PXE</acronym></title>
- <para>By default, the &man.pxeboot.8; loader loads the kernel
- via <acronym>NFS</acronym>. It can be compiled to use
+ <para>By default, &man.pxeboot.8; loads the kernel via
+ <acronym>NFS</acronym>. It can be compiled to use
<acronym>TFTP</acronym> instead by specifying the
<literal>LOADER_TFTP_SUPPORT</literal> option in
<filename>/etc/make.conf</filename>. See the comments in
@@ -4068,10 +3999,9 @@ margaux:ha=0123456789ab:tc=.def100</programlisting>
<literal>BOOT_PXELDR_ALWAYS_SERIAL</literal>.</para>
<para>To use <acronym>PXE</acronym> when the machine starts,
- you will usually need to select the <literal>Boot from
- network</literal> option in your <acronym>BIOS</acronym>
- setup, or type a function key during the PC
- initialization.</para>
+ select the <literal>Boot from network</literal> option in
+ the <acronym>BIOS</acronym> setup or type a function key
+ during system initialization.</para>
</sect3>
<sect3>
@@ -4087,27 +4017,26 @@ margaux:ha=0123456789ab:tc=.def100</programlisting>
<secondary>diskless operation</secondary>
</indexterm>
- <para>If you are using <acronym>PXE</acronym> or
- <application>Etherboot</application> configured to use
- <acronym>TFTP</acronym>, you need to enable
- <application>tftpd</application> on the file server:</para>
+ <para>If <acronym>PXE</acronym> is configured to use
+ <acronym>TFTP</acronym>, enable &man.tftpd.8; on the file
+ server:</para>
<procedure>
<step>
- <para>Create a directory from which
- <application>tftpd</application> will serve the files,
- e.g., <filename class="directory">/tftpboot</filename>.</para>
+ <para>Create a directory from which &man.tftpd.8; will
+ serve the files, such as <filename
+ class="directory">/tftpboot</filename>.</para>
</step>
<step>
- <para>Add this line to your
+ <para>Add this line to
<filename>/etc/inetd.conf</filename>:</para>
<programlisting>tftp dgram udp wait root /usr/libexec/tftpd tftpd -l -s /tftpboot</programlisting>
<note>
- <para>It appears that at least some
- <acronym>PXE</acronym> versions want the
+ <para>Some
+ <acronym>PXE</acronym> versions require the
<acronym>TCP</acronym> version of
<acronym>TFTP</acronym>. In this case, add a second
line, replacing <literal>dgram udp</literal> with
@@ -4116,29 +4045,27 @@ margaux:ha=0123456789ab:tc=.def100</programlisting>
</step>
<step>
- <para>Tell <application>inetd</application> to reread its
- configuration file. The
- <option>inetd_enable="YES"</option> must be in the
- <filename>/etc/rc.conf</filename> file for this command
- to execute correctly:</para>
+ <para>Tell &man.inetd.8; to reread its configuration file.
+ Add <option>inetd_enable="YES"</option> to
+ <filename>/etc/rc.conf</filename> in order for this
+ command to execute correctly:</para>
<screen>&prompt.root; <userinput>service inetd restart</userinput></screen>
</step>
</procedure>
- <para>You can place
- the <filename class="directory">tftpboot</filename>
- directory anywhere on the server. Make sure that the
- location is set in both <filename>inetd.conf</filename> and
- <filename>dhcpd.conf</filename>.</para>
+ <para>Place <filename class="directory">tftpboot</filename>
+ anywhere on the server. Make sure that the location is
+ set in both <filename>/etc/inetd.conf</filename> and
+ <filename>/usr/local/etc/dhcpd.conf</filename>.</para>
- <para>In all cases, you also need to enable
+ <para>Enable
<acronym>NFS</acronym> and export the appropriate file
system on the <acronym>NFS</acronym> server.</para>
<procedure>
<step>
- <para>Add this to
+ <para>Add this line to
<filename>/etc/rc.conf</filename>:</para>
<programlisting>nfs_server_enable="YES"</programlisting>
@@ -4147,20 +4074,19 @@ margaux:ha=0123456789ab:tc=.def100</programlisting>
<step>
<para>Export the file system where the diskless root
directory is located by adding the following to
- <filename>/etc/exports</filename> (adjust the volume
- mount point and replace <replaceable>margaux
+ <filename>/etc/exports</filename>. Adjust the
+ mount point and replace <replaceable>
corbieres</replaceable> with the names of the diskless
- workstations):</para>
+ workstations:</para>
<programlisting><replaceable>/data/misc</replaceable> -alldirs -ro <replaceable>margaux corbieres</replaceable></programlisting>
</step>
<step>
- <para>Tell <application>mountd</application> to reread its
- configuration file. If you actually needed to enable
- <acronym>NFS</acronym> in
- <filename>/etc/rc.conf</filename> at the first step, you
- probably want to reboot instead.</para>
+ <para>Tell &man.mountd.8; to reread its configuration
+ file. If <acronym>NFS</acronym> is enabled in
+ <filename>/etc/rc.conf</filename>, it is recommended
+ to reboot instead.</para>
<screen>&prompt.root; <userinput>service mountd restart</userinput></screen>
</step>
@@ -4175,76 +4101,58 @@ margaux:ha=0123456789ab:tc=.def100</programlisting>
<secondary>kernel configuration</secondary>
</indexterm>
- <para>If using <application>Etherboot</application>, you need
- to create a kernel configuration file for the diskless
- client with the following options (in addition to the usual
- ones):</para>
+ <para>When using <acronym>PXE</acronym>, building a custom
+ kernel with the following options is not strictly necessary.
+ These options cause more <acronym>DHCP</acronym> requests
+ to be issued during kernel startup, with a small risk of
+ inconsistency between the new values and those retrieved
+ by &man.pxeboot.8; in some special cases. The advantage
+ is that the host name will be set. Otherwise, set the
+ host name in a client-specific
+ <filename>/etc/rc.conf</filename>.</para>
<programlisting>options BOOTP # Use BOOTP to obtain IP address/hostname
options BOOTP_NFSROOT # NFS mount root file system using BOOTP info</programlisting>
- <para>You may also want to use <literal>BOOTP_NFSV3</literal>,
+ <para>The custom kernel can also include
+ <literal>BOOTP_NFSV3</literal>,
<literal>BOOT_COMPAT</literal> and
- <literal>BOOTP_WIRED_TO</literal> (refer to
- <filename>NOTES</filename>).</para>
+ <literal>BOOTP_WIRED_TO</literal>. Refer to
+ <filename>NOTES</filename> for descriptions of these
+ options.</para>
<para>These option names are historical and slightly
misleading as they actually enable indifferent use of
- <acronym>DHCP</acronym> and BOOTP inside the kernel (it is
- also possible to force strict BOOTP or
- <acronym>DHCP</acronym> use).</para>
-
- <para>Build the kernel (see <xref linkend="kernelconfig"/>),
- and copy it to the place specified in
- <filename>dhcpd.conf</filename>.</para>
-
- <note>
- <para>When using <acronym>PXE</acronym>, building a kernel
- with the above options is not strictly necessary (though
- suggested). Enabling them will cause more
- <acronym>DHCP</acronym> requests to be issued during
- kernel startup, with a small risk of inconsistency between
- the new values and those retrieved by &man.pxeboot.8; in
- some special cases. The advantage of using them is that
- the host name will be set as a side effect. Otherwise you
- will need to set the host name by another method, for
- example in a client-specific <filename>rc.conf</filename>
- file.</para>
- </note>
+ <acronym>DHCP</acronym> and <acronym>BOOTP</acronym>
+ inside the kernel.</para>
- <note>
- <para>In order to be loadable with
- <application>Etherboot</application>, a kernel needs to
- have the device hints compiled in. You would typically
- set the following option in the configuration file (see
- the <filename>NOTES</filename> configuration comments
- file):</para>
-
- <programlisting>hints "GENERIC.hints"</programlisting>
- </note>
+ <para>Build the custom kernel, using the instructions in
+ <xref linkend="kernelconfig"/>, and copy it to the place
+ specified in
+ <filename>/usr/local/etc/dhcpd.conf</filename>.</para>
</sect3>
<sect3>
- <title>Preparing the Root Filesystem</title>
+ <title>Preparing the Root File System</title>
<indexterm>
<primary>root file system</primary>
<secondary>diskless operation</secondary>
</indexterm>
- <para>You need to create a root file system for the diskless
- workstations, in the location listed as
+ <para>Create a root file system for the diskless
+ workstations in the location listed as
<literal>root-path</literal> in
- <filename>dhcpd.conf</filename>.</para>
+ <filename>/usr/local/etc/dhcpd.conf</filename>.</para>
<sect4>
<title>Using <command>make world</command> to Populate
Root</title>
<para>This method is quick and will install a complete
- virgin system (not only the root file system) into
- <envar>DESTDIR</envar>. All you have to do is simply
- execute the following script:</para>
+ virgin system, not just the root file system, into
+ <envar>DESTDIR</envar>. Execute the following
+ script:</para>
<programlisting>#!/bin/sh
export DESTDIR=/data/misc/diskless
@@ -4253,10 +4161,11 @@ cd /usr/src; make buildworld &amp;&amp; make buildkernel
make installworld &amp;&amp; make installkernel
cd /usr/src/etc; make distribution</programlisting>
- <para>Once done, you may need to customize your
+ <para>Once done, customize
<filename>/etc/rc.conf</filename> and
<filename>/etc/fstab</filename> placed into
- <envar>DESTDIR</envar> according to your needs.</para>
+ <envar>DESTDIR</envar> according to the system's
+ requirements.</para>
</sect4>
</sect3>
@@ -4273,13 +4182,12 @@ cd /usr/src/etc; make distribution</programlisting>
<acronym>NFS</acronym> swap at boot time. Swap must be
enabled by the startup scripts, by mounting a writable
file system and creating and enabling a swap file. To
- create a swap file of appropriate size, you can do like
- this:</para>
+ create a swap file:</para>
<screen>&prompt.root; <userinput>dd if=/dev/zero of=<replaceable>/path/to/swapfile</replaceable> bs=1k count=1 oseek=<replaceable>100000</replaceable></userinput></screen>
- <para>To enable it you have to add the following line to
- your <filename>rc.conf</filename>:</para>
+ <para>To enable the swap file, add the following line to
+ <filename>/etc/rc.conf</filename>:</para>
<programlisting>swapfile=<replaceable>/path/to/swapfile</replaceable></programlisting>
</sect4>
@@ -4289,39 +4197,37 @@ cd /usr/src/etc; make distribution</programlisting>
<title>Miscellaneous Issues</title>
<sect4>
- <title>Running with a Read-only
- <filename class="directory">/usr</filename></title>
+ <title>Running with a Read-only <filename
+ class="directory">/usr</filename></title>
<indexterm>
<primary>diskless operation</primary>
<secondary>/usr read-only</secondary>
</indexterm>
- <para>If the diskless workstation is configured to run X,
- you will have to adjust the
- <application>XDM</application> configuration file, which
- puts the error log
- on <filename class="directory">/usr</filename> by
- default.</para>
+ <para>If the diskless workstation is configured to run
+ <application>&xorg;</application>, adjust the
+ <application>XDM</application> configuration file as it
+ puts the error log on <filename
+ class="directory">/usr</filename> by default.</para>
</sect4>
<sect4>
- <title>Using a Non-FreeBSD Server</title>
+ <title>Using a Non-&os; Server</title>
<para>When the server for the root file system is not
- running FreeBSD, you will have to create the root file
- system on a FreeBSD machine, then copy it to its
- destination, using <command>tar</command> or
- <command>cpio</command>.</para>
+ running &os;, create the root file system on a &os;
+ machine, then copy it to its destination, using
+ &man.tar.1; or &man.cpio.1;.</para>
<para>In this situation, there are sometimes problems with
- the special files
- in <filename class="directory">/dev</filename>, due to
- differing major/minor integer sizes. A solution to this
- problem is to export a directory from the non-FreeBSD
- server, mount this directory onto a FreeBSD machine, and
- use &man.devfs.5; to allocate device nodes transparently
- for the user.</para>
+ the special files in <filename
+ class="directory">/dev</filename>, due to differing
+ major/minor integer sizes. A solution to this problem
+ is to export a directory from the non-&os; server, mount
+ this directory onto a &os; machine, and use &man.devfs.5;
+ to allocate device nodes transparently for the
+ user.</para>
</sect4>
</sect3>
</sect2>
@@ -4340,63 +4246,67 @@ cd /usr/src/etc; make distribution</programlisting>
</author>
</authorgroup>
</sect1info>
- <title>PXE Booting with an NFS Root File System</title>
+ <title>PXE Booting with an <acronym>NFS</acronym> Root File
+ System</title>
<para>The &intel; Preboot eXecution Environment
(<acronym>PXE</acronym>) allows booting the operating system
over the network. <acronym>PXE</acronym> support is usually
- provided in the <acronym>BIOS</acronym> of modern motherboards,
- where it can be enabled in the <acronym>BIOS</acronym> settings
- which enable booting from the network. A fully functioning
+ provided in the <acronym>BIOS</acronym> where it can be enabled
+ in the <acronym>BIOS</acronym> settings which enable booting
+ from the network. A fully functioning
<acronym>PXE</acronym> setup also requires properly configured
<acronym>DHCP</acronym> and <acronym>TFTP</acronym>
servers.</para>
<para>When the host computer boots, it receives information over
<acronym>DHCP</acronym> about where to obtain the initial boot
- loader via TFTP. After the host computer receives this
- information, it downloads the boot loader via
- <acronym>TFTP</acronym>, and then executes the boot loader.
+ loader via <acronym>TFTP</acronym>. After the host computer
+ receives this information, it downloads the boot loader via
+ <acronym>TFTP</acronym> and then executes the boot loader.
This is documented in section 2.2.1 of the <ulink
url="http://download.intel.com/design/archives/wfm/downloads/pxespec.pdf">Preboot
- Execution Environment (PXE) Specification</ulink>. In &os;,
- the boot loader retrieved during the <acronym>PXE</acronym>
- process is <filename>/boot/pxeboot</filename>. After
+ Execution Environment (<acronym>PXE</acronym>)
+ Specification</ulink>. In &os;, the boot loader retrieved
+ during the <acronym>PXE</acronym> process is
+ <filename>/boot/pxeboot</filename>. After
<filename>/boot/pxeboot</filename> executes, the &os; kernel is
- loaded, and the rest of the &os; bootup sequence proceeds.
+ loaded and the rest of the &os; bootup sequence proceeds.
Refer to <xref linkend="boot"/> for more information about the
&os; booting process.</para>
<sect2>
- <title>Setting Up the <command>chroot</command> Environment for
- the NFS Root File System</title>
+ <title>Setting Up the &man.chroot.8; Environment for the
+ <acronym>NFS</acronym> Root File System</title>
<procedure>
<step>
<para>Choose a directory which will have a &os;
- installation which will be NFS mountable. For example, a
- directory such as
- <filename class="directory">/b/tftpboot/FreeBSD/install</filename> can be
- used.</para>
+ installation which will be <acronym>NFS</acronym>
+ mountable. For example, a directory such as <filename
+ class="directory">/b/tftpboot/FreeBSD/install</filename>
+ can be used.</para>
<screen>&prompt.root; <userinput>export NFSROOTDIR=/b/tftpboot/FreeBSD/install</userinput>
&prompt.root; <userinput>mkdir -p ${NFSROOTDIR}</userinput></screen>
</step>
<step>
- <para>Enable the NFS server by following the instructions
- in <xref linkend="network-configuring-nfs"/>.</para>
+ <para>Enable the <acronym>NFS</acronym> server by following
+ the instructions in <xref
+ linkend="network-configuring-nfs"/>.</para>
</step>
<step>
- <para>Export the directory via NFS by adding the following
- to <filename>/etc/exports</filename>:</para>
+ <para>Export the directory via <acronym>NFS</acronym> by
+ adding the following to
+ <filename>/etc/exports</filename>:</para>
<programlisting>/b -ro -alldirs</programlisting>
</step>
<step>
- <para>Restart the NFS server:</para>
+ <para>Restart the <acronym>NFS</acronym> server:</para>
<screen>&prompt.root; <userinput>service nfsd restart</userinput></screen>
</step>
@@ -4414,14 +4324,14 @@ cd /usr/src/etc; make distribution</programlisting>
</step>
<step>
- <para>Restart inetd:</para>
+ <para>Restart &man.inetd.8;:</para>
<screen>&prompt.root; <userinput>service inetd restart</userinput></screen>
</step>
<step>
- <para><link linkend="makeworld">Rebuild the &os; kernel and
- userland</link>:</para>
+ <para>Rebuild the &os; kernel and userland (<xref
+ linkend="makeworld"/>):</para>
<screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make buildworld</userinput>
@@ -4438,9 +4348,9 @@ cd /usr/src/etc; make distribution</programlisting>
</step>
<step>
- <para>Test that the <acronym>TFTP</acronym> server works and
- can download the boot loader which will be obtained
- via PXE:</para>
+ <para>Test that the <acronym>TFTP</acronym> server works
+ and can download the boot loader which will be obtained
+ via <acronym>PXE</acronym>:</para>
<screen>&prompt.root; <userinput>tftp localhost</userinput>
tftp> <userinput>get FreeBSD/install/boot/pxeboot</userinput>
@@ -4450,38 +4360,36 @@ Received 264951 bytes in 0.1 seconds</screen>
<step>
<para>Edit <filename>${NFSROOTDIR}/etc/fstab</filename> and
create an entry to mount the root file system over
- NFS:</para>
+ <acronym>NFS</acronym>:</para>
<programlisting># Device Mountpoint FSType Options Dump Pass
myhost.example.com:/b/tftpboot/FreeBSD/install / nfs ro 0 0</programlisting>
- <para>Replace
- <replaceable>myhost.example.com</replaceable> with the
- hostname or IP address of your <acronym>NFS</acronym>
- server. In this example, the root file system is mounted
- "read-only" in order to prevent <acronym>NFS</acronym>
- clients from potentially deleting the contents of the root
- file system.</para>
+ <para>Replace <replaceable>myhost.example.com</replaceable>
+ with the hostname or <acronym>IP</acronym> address of the
+ <acronym>NFS</acronym> server. In this example, the root
+ file system is mounted read-only in order to prevent
+ <acronym>NFS</acronym> clients from potentially deleting
+ the contents of the root file system.</para>
</step>
<step>
<para>Set the root password in the &man.chroot.8;
- environment.</para>
+ environment:</para>
<screen>&prompt.root; <userinput>chroot ${NFSROOTDIR}</userinput>
&prompt.root; <userinput>passwd</userinput></screen>
- <para>This will set the root password for client
- machines which are <acronym>PXE</acronym>
- booting.</para>
+ <para>This sets the root password for client machines which
+ are <acronym>PXE</acronym> booting.</para>
</step>
<step>
- <para>Enable ssh root logins for client machines which are
- <acronym>PXE</acronym> booting by editing
- <filename>${NFSROOTDIR}/etc/ssh/sshd_config</filename> and
- enabling the <literal>PermitRootLogin</literal> option.
- This is documented in &man.sshd.config.5;.</para>
+ <para>Enable &man.ssh.1; root logins for client machines
+ which are <acronym>PXE</acronym> booting by editing
+ <filename>${NFSROOTDIR}/etc/ssh/sshd_config</filename>
+ and enabling <literal>PermitRootLogin</literal>. This
+ option is documented in &man.sshd.config.5;.</para>
</step>
<step>
@@ -4502,44 +4410,43 @@ myhost.example.com:/b/tftpboot/FreeBSD/install / nfs ro
<title>Configuring Memory File Systems Used by
<filename>/etc/rc.initdiskless</filename></title>
- <para>If you boot from an NFS root volume,
- <filename>/etc/rc</filename> detects that you booted over NFS
- and runs the <filename>/etc/rc.initdiskless</filename> script.
- Read the comments in this script to understand what is going
- on. We need to
- make <filename class="directory">/etc</filename>
- and <filename class="directory">/var</filename>
- memory backed file systems because
- these directories need to be writable, but the NFS root
- directory is read-only.</para>
+ <para>When booting from an <acronym>NFS</acronym> root volume,
+ <filename>/etc/rc</filename> detects the
+ <acronym>NFS</acronym> boot and runs
+ <filename>/etc/rc.initdiskless</filename>. Read the comments
+ in this script to understand what is going on. In this case,
+ <filename class="directory">/etc</filename> and <filename
+ class="directory">/var</filename> need to be memory backed
+ file systems so that these directories are writable but the
+ <acronym>NFS</acronym> root directory is read-only:</para>
<screen>&prompt.root; <userinput>chroot ${NFSROOTDIR}</userinput>
&prompt.root; <userinput>mkdir -p conf/base</userinput>
&prompt.root; <userinput>tar -c -v -f conf/base/etc.cpio.gz --format cpio --gzip etc</userinput>
&prompt.root; <userinput>tar -c -v -f conf/base/var.cpio.gz --format cpio --gzip var</userinput></screen>
- <para>When the system boots, memory file systems
- for <filename class="directory">/etc</filename>
- and <filename class="directory">/var</filename> will
- be created and mounted, and the contents of the
+ <para>When the system boots, memory file systems for <filename
+ class="directory">/etc</filename> and <filename
+ class="directory">/var</filename> will be created and
+ mounted and the contents of the
<filename>cpio.gz</filename> files will be copied into
them.</para>
</sect2>
<sect2 id="network-pxe-setting-up-dhcp">
- <title>Setting up the DHCP Server</title>
+ <title>Setting up the <acronym>DHCP</acronym> Server</title>
- <para>PXE requires a <acronym>TFTP</acronym> server and a
- <acronym>DHCP</acronym> server to be set up. The
- <acronym>DHCP</acronym> server does not necessarily need to be
- the same machine as the <acronym>TFTP</acronym> server, but it
- needs to be accessible in your network.</para>
+ <para><acronym>PXE</acronym> requires a <acronym>TFTP</acronym>
+ and a <acronym>DHCP</acronym> server to be set up. The
+ <acronym>DHCP</acronym> server does not need to be the same
+ machine as the <acronym>TFTP</acronym> server, but it needs
+ to be accessible in the network.</para>
<procedure>
<step>
<para>Install the <acronym>DHCP</acronym> server by
- following the instructions documented at
- <xref linkend="network-dhcp-server"/>. Make sure that
+ following the instructions documented at <xref
+ linkend="network-dhcp-server"/>. Make sure that
<filename>/etc/rc.conf</filename> and
<filename>/usr/local/etc/dhcpd.conf</filename> are
correctly configured.</para>
@@ -4549,10 +4456,10 @@ myhost.example.com:/b/tftpboot/FreeBSD/install / nfs ro
<para>In <filename>/usr/local/etc/dhcpd.conf</filename>,
configure the <literal>next-server</literal>,
<literal>filename</literal>, and
- <literal>option root-path</literal> settings, to specify
- your <acronym>TFTP</acronym> server IP address, the path
- to <filename>/boot/pxeboot</filename> in
- <acronym>TFTP</acronym>, and the path to the
+ <literal>option root-path</literal> settings to specify
+ the <acronym>TFTP</acronym> server <acronym>IP</acronym>
+ address, the path to <filename>/boot/pxeboot</filename>
+ in <acronym>TFTP</acronym>, and the path to the
<acronym>NFS</acronym> root file system. Here is a sample
<filename>dhcpd.conf</filename> setup:</para>
@@ -4580,33 +4487,34 @@ myhost.example.com:/b/tftpboot/FreeBSD/install / nfs ro
</sect2>
<sect2>
- <title>Configuring the PXE Client and Debugging Connection
- Problems</title>
+ <title>Configuring the <acronym>PXE</acronym> Client and
+ Debugging Connection Problems</title>
<procedure>
<step>
<para>When the client machine boots up, enter the
<acronym>BIOS</acronym> configuration menu. Configure the
<acronym>BIOS</acronym> to boot from the network. If all
- your previous configuration steps are correct, then
- everything should &quot;just work&quot;.</para>
+ previous configuration steps are correct, everything
+ should &quot;just work&quot;.</para>
</step>
<step>
- <para>Use the
- <filename role="package">net/wireshark</filename> port to
- debug the network traffic involved during the
- <acronym>PXE</acronym> booting process, which is
- illustrated in the diagram below. In
- <xref linkend="network-pxe-setting-up-dhcp"/>, an example
+ <para>Use the <filename
+ role="package">net/wireshark</filename> package or
+ port to debug the network traffic involved during the
+ <acronym>PXE</acronym> booting process, as illustrated
+ in the diagram below. In <xref
+ linkend="network-pxe-setting-up-dhcp"/>, an example
configuration is shown where the <acronym>DHCP</acronym>,
<acronym>TFTP</acronym>, and <acronym>NFS</acronym>
- servers are actually on the same machine. However, these
- severs can be on separate machines.</para>
+ servers are on the same machine. However, these
+ servers can be on separate machines.</para>
<figure>
- <title>PXE Booting Process with NFS Root Mount</title>
+ <title><acronym>PXE</acronym> Booting Process with
+ <acronym>NFS</acronym> Root Mount</title>
<mediaobjectco>
<imageobjectco>
@@ -4622,32 +4530,34 @@ myhost.example.com:/b/tftpboot/FreeBSD/install / nfs ro
</imageobject>
<calloutlist>
<callout arearefs="co-pxenfs1">
- <para>Client broadcasts DHCPDISCOVER.</para>
+ <para>Client broadcasts a
+ <literal>DHCPDISCOVER</literal> message.</para>
</callout>
<callout arearefs="co-pxenfs2">
- <para>DHCP server responds with IP address,
+ <para>The <acronym>DHCP</acronym> server responds
+ with the <acronym>IP</acronym> address,
<literal>next-server</literal>,
<literal>filename</literal>, and
- <literal>root-path</literal>.</para>
+ <literal>root-path</literal> values.</para>
</callout>
<callout arearefs="co-pxenfs3">
- <para>Client sends <acronym>TFTP</acronym>
- request to <literal>next-server</literal>
+ <para>The client sends a <acronym>TFTP</acronym>
+ request to <literal>next-server</literal>,
asking to retrieve
<literal>filename</literal>.</para>
</callout>
<callout arearefs="co-pxenfs4">
- <para>TFTP server responds and sends
- <literal>filename</literal> to client.</para>
+ <para>The <acronym>TFTP</acronym> server responds
+ and sends <literal>filename</literal> to
+ client.</para>
</callout>
<callout arearefs="co-pxenfs5">
- <para>Client executes
- <literal>filename</literal> which is
- &man.pxeboot.8;. &man.pxeboot.8; loads the
- kernel. When the kernel executes, the root
- filesystem specified by
- <literal>root-path</literal> is mounted over
- <acronym>NFS</acronym>.</para>
+ <para>The client executes
+ <literal>filename</literal>, which is
+ &man.pxeboot.8;, which then loads the kernel.
+ When the kernel executes, the root file system
+ specified by <literal>root-path</literal> is
+ mounted over <acronym>NFS</acronym>.</para>
</callout>
</calloutlist>
</imageobjectco>
@@ -4657,26 +4567,26 @@ myhost.example.com:/b/tftpboot/FreeBSD/install / nfs ro
<step>
<para>Make sure that the <filename>pxeboot</filename> file
- can be retrieved by <acronym>TFTP</acronym>. On your
- <acronym>TFTP</acronym> server, look in
+ can be retrieved by <acronym>TFTP</acronym>. On the
+ <acronym>TFTP</acronym> server, read
<filename>/var/log/xferlog</filename> to ensure that the
<filename>pxeboot</filename> file is being retrieved from
- the correct location. To test the configuration from
- <filename>dhcpd.conf</filename> above:</para>
+ the correct location. To test this example
+ configuration:</para>
<screen>&prompt.root; <userinput>tftp 192.168.0.1</userinput>
tftp> <userinput>get FreeBSD/install/boot/pxeboot</userinput>
Received 264951 bytes in 0.1 seconds</screen>
- <para>Read &man.tftpd.8; and &man.tftp.1;. The
- <literal>BUGS</literal> sections in these pages document
- some limitations with <acronym>TFTP</acronym>.</para>
+ <para>The <literal>BUGS</literal> sections in &man.tftpd.8;
+ and &man.tftp.1; document some limitations with
+ <acronym>TFTP</acronym>.</para>
</step>
<step>
<para>Make sure that the root file system can be mounted
- via <acronym>NFS</acronym>. To test configuration from
- <filename>dhcpd.conf</filename> above:</para>
+ via <acronym>NFS</acronym>. To test this example
+ configuration:</para>
<screen>&prompt.root; <userinput>mount -t nfs 192.168.0.1:/b/tftpboot/FreeBSD/install /mnt</userinput></screen>
</step>
@@ -4687,7 +4597,8 @@ Received 264951 bytes in 0.1 seconds</screen>
understand how the <filename>pxeboot</filename> loader
sets variables like <literal>boot.nfsroot.server</literal>
and <literal>boot.nfsroot.path</literal>. These variables
- are then used in the NFS diskless root mount code in
+ are then used in the <acronym>NFS</acronym> diskless root
+ mount code in
<filename>src/sys/nfsclient/nfs_diskless.c</filename>.</para>
</step>
@@ -4698,332 +4609,6 @@ Received 264951 bytes in 0.1 seconds</screen>
</sect2>
</sect1>
- <sect1 id="network-isdn">
- <title>ISDN</title>
-
- <indexterm>
- <primary>ISDN</primary>
- </indexterm>
-
- <para>A good resource for information on ISDN technology and
- hardware is
- <ulink url="http://www.alumni.caltech.edu/~dank/isdn/">Dan
- Kegel's ISDN Page</ulink>.</para>
-
- <para>A quick simple road map to ISDN follows:</para>
-
- <itemizedlist>
- <listitem>
- <para>If you live in Europe you might want to investigate the
- ISDN card section.</para>
- </listitem>
-
- <listitem>
- <para>If you are planning to use ISDN primarily to connect to
- the Internet with an Internet Provider on a dial-up
- non-dedicated basis, you might look into Terminal Adapters.
- This will give you the most flexibility, with the fewest
- problems, if you change providers.</para>
- </listitem>
-
- <listitem>
- <para>If you are connecting two LANs together, or connecting
- to the Internet with a dedicated ISDN connection, you might
- consider the stand alone router/bridge option.</para>
- </listitem>
- </itemizedlist>
-
- <para>Cost is a significant factor in determining what solution
- you will choose. The following options are listed from least
- expensive to most expensive.</para>
-
- <sect2 id="network-isdn-cards">
- <sect2info>
- <authorgroup>
- <author>
- <firstname>Hellmuth</firstname>
- <surname>Michaelis</surname>
- <contrib>Contributed by </contrib>
- </author>
- </authorgroup>
- </sect2info>
- <title>ISDN Cards</title>
-
- <indexterm>
- <primary>ISDN</primary>
- <secondary>cards</secondary>
- </indexterm>
-
- <para>FreeBSD's ISDN implementation supports only the DSS1/Q.931
- (or Euro-ISDN) standard using passive cards. Some active
- cards are supported where the firmware also supports other
- signaling protocols; this also includes the first supported
- Primary Rate (PRI) ISDN card.</para>
-
- <para>The <application>isdn4bsd</application> software allows
- you to connect to other ISDN routers using either IP over raw
- HDLC or by using synchronous PPP: either by using kernel PPP
- with <literal>isppp</literal>, a modified &man.sppp.4; driver,
- or by using userland &man.ppp.8;. By using userland
- &man.ppp.8;, channel bonding of two or more ISDN B-channels is
- possible. A telephone answering machine application is also
- available as well as many utilities such as a software 300
- Baud modem.</para>
-
- <para>Some growing number of PC ISDN cards are supported under
- FreeBSD and the reports show that it is successfully used all
- over Europe and in many other parts of the world.</para>
-
- <para>The passive ISDN cards supported are mostly the ones with
- the Infineon (formerly Siemens) ISAC/HSCX/IPAC ISDN chipsets,
- but also ISDN cards with chips from Cologne Chip (ISA bus
- only), PCI cards with Winbond W6692 chips, some cards with the
- Tiger300/320/ISAC chipset combinations and some vendor
- specific chipset based cards such as the AVM Fritz!Card PCI
- V.1.0 and the AVM Fritz!Card PnP.</para>
-
- <para>Currently the active supported ISDN cards are the AVM B1
- (ISA and PCI) BRI cards and the AVM T1 PCI PRI cards.</para>
-
- <para>For documentation on <application>isdn4bsd</application>,
- have a look at the
- <ulink url="http://www.freebsd-support.de/i4b/">homepage of
- isdn4bsd</ulink> which also has pointers to hints, erratas
- and much more documentation such as the <ulink
- url="http://people.FreeBSD.org/~hm/">isdn4bsd
- handbook</ulink>.</para>
-
- <para>In case you are interested in adding support for a
- different ISDN protocol, a currently unsupported ISDN PC card
- or otherwise enhancing <application>isdn4bsd</application>,
- please get in touch with &a.hm;.</para>
-
- <para>For questions regarding the installation, configuration
- and troubleshooting <application>isdn4bsd</application>, a
- &a.isdn.name; mailing list is available.</para>
- </sect2>
-
- <sect2>
- <title>ISDN Terminal Adapters</title>
-
- <para>Terminal adapters (TA), are to ISDN what modems are to
- regular phone lines.</para>
-
- <indexterm><primary>modem</primary></indexterm>
- <para>Most TA's use the standard Hayes modem AT command set, and
- can be used as a drop in replacement for a modem.</para>
-
- <para>A TA will operate basically the same as a modem except
- connection and throughput speeds will be much faster than your
- old modem. You will need to configure
- <link linkend="ppp">PPP</link> exactly the same as for a modem
- setup. Make sure you set your serial speed as high as
- possible.</para>
-
- <indexterm><primary>PPP</primary></indexterm>
- <para>The main advantage of using a TA to connect to an Internet
- Provider is that you can do Dynamic PPP. As IP address space
- becomes more and more scarce, most providers are not willing
- to provide you with a static IP any more. Most stand-alone
- routers are not able to accommodate dynamic IP
- allocation.</para>
-
- <para>TA's completely rely on the PPP daemon that you are
- running for their features and stability of connection. This
- allows you to upgrade easily from using a modem to ISDN on a
- FreeBSD machine, if you already have PPP set up. However, at
- the same time any problems you experienced with the PPP
- program and are going to persist.</para>
-
- <para>If you want maximum stability, use the kernel
- <link linkend="ppp">PPP</link> option, not the
- <link linkend="userppp">userland PPP</link>.</para>
-
- <para>The following TA's are known to work with FreeBSD:</para>
-
- <itemizedlist>
- <listitem>
- <para>Motorola BitSurfer and Bitsurfer Pro</para>
- </listitem>
-
- <listitem>
- <para>Adtran</para>
- </listitem>
- </itemizedlist>
-
- <para>Most other TA's will probably work as well, TA vendors try
- to make sure their product can accept most of the standard
- modem AT command set.</para>
-
- <para>The real problem with external TA's is that, like modems,
- you need a good serial card in your computer.</para>
-
- <para>You should read the <ulink
- url="&url.articles.serial-uart;/index.html">FreeBSD Serial
- Hardware</ulink> tutorial for a detailed understanding of
- serial devices, and the differences between asynchronous and
- synchronous serial ports.</para>
-
- <para>A TA running off a standard PC serial port (asynchronous)
- limits you to 115.2&nbsp;Kbs, even though you have a
- 128&nbsp;Kbs connection. To fully utilize the 128&nbsp;Kbs
- that ISDN is capable of, you must move the TA to a synchronous
- serial card.</para>
-
- <para>Do not be fooled into buying an internal TA and thinking
- you have avoided the synchronous/asynchronous issue. Internal
- TA's simply have a standard PC serial port chip built into
- them. All this will do is save you having to buy another
- serial cable and find another empty electrical socket.</para>
-
- <para>A synchronous card with a TA is at least as fast as a
- stand-alone router, and with a simple 386 FreeBSD box driving
- it, probably more flexible.</para>
-
- <para>The choice of synchronous card/TA versus stand-alone
- router is largely a religious issue. There has been some
- discussion of this in the mailing lists. We suggest you
- search the
- <ulink url="&url.base;/search/index.html">archives</ulink> for
- the complete discussion.</para>
- </sect2>
-
- <sect2>
- <title>Stand-alone ISDN Bridges/Routers</title>
-
- <indexterm>
- <primary>ISDN</primary>
- <secondary>stand-alone bridges/routers</secondary>
- </indexterm>
- <para>ISDN bridges or routers are not at all specific to FreeBSD
- or any other operating system. For a more complete
- description of routing and bridging technology, please refer
- to a networking reference book.</para>
-
- <para>In the context of this section, the terms router and
- bridge will be used interchangeably.</para>
-
- <para>As the cost of low end ISDN routers/bridges comes down, it
- will likely become a more and more popular choice. An ISDN
- router is a small box that plugs directly into your local
- Ethernet network, and manages its own connection to the other
- bridge/router. It has built in software to communicate via
- PPP and other popular protocols.</para>
-
- <para>A router will allow you much faster throughput than a
- standard TA, since it will be using a full synchronous ISDN
- connection.</para>
-
- <para>The main problem with ISDN routers and bridges is that
- interoperability between manufacturers can still be a problem.
- If you are planning to connect to an Internet provider, you
- should discuss your needs with them.</para>
-
- <para>If you are planning to connect two LAN segments together,
- such as your home LAN to the office LAN, this is the simplest
- lowest
- maintenance solution. Since you are buying the equipment for
- both sides of the connection you can be assured that the link
- will work.</para>
-
- <para>For example to connect a home computer or branch office
- network to a head office network the following setup could be
- used:</para>
-
- <example>
- <title>Branch Office or Home Network</title>
-
- <indexterm><primary>10 base 2</primary></indexterm>
- <para>Network uses a bus based topology with 10 base 2
- Ethernet (<quote>thinnet</quote>). Connect router to
- network cable with AUI/10BT transceiver, if
- necessary.</para>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="advanced-networking/isdn-bus"/>
- </imageobject>
-
- <textobject>
- <literallayout class="monospaced">---Sun workstation
-|
----FreeBSD box
-|
----Windows 95
-|
-Stand-alone router
- |
-ISDN BRI line</literallayout>
- </textobject>
-
- <textobject>
- <phrase>10 Base 2 Ethernet</phrase>
- </textobject>
- </mediaobject>
-
- <para>If your home/branch office is only one computer you can
- use a twisted pair crossover cable to connect to the
- stand-alone router directly.</para>
- </example>
-
- <example>
- <title>Head Office or Other LAN</title>
-
- <indexterm><primary>10 base T</primary></indexterm>
- <para>Network uses a star topology with 10 base T Ethernet
- (<quote>Twisted Pair</quote>).</para>
-
- <mediaobject>
- <imageobject>
- <imagedata
- fileref="advanced-networking/isdn-twisted-pair"/>
- </imageobject>
-
- <textobject>
- <literallayout class="monospaced"> -------Novell Server
- | H |
- | ---Sun
- | |
- | U ---FreeBSD
- | |
- | ---Windows 95
- | B |
- |___---Stand-alone router
- |
- ISDN BRI line</literallayout>
- </textobject>
-
- <textobject>
- <phrase>ISDN Network Diagram</phrase>
- </textobject>
- </mediaobject>
- </example>
-
- <para>One large advantage of most routers/bridges is that they
- allow you to have 2 <emphasis>separate independent</emphasis>
- PPP connections to 2 separate sites at the
- <emphasis>same</emphasis> time. This is not supported on most
- TA's, except for specific (usually expensive) models that have
- two serial ports. Do not confuse this with channel bonding,
- MPP, etc.</para>
-
- <para>This can be a very useful feature if, for example, you
- have an dedicated ISDN connection at your office and would
- like to tap into it, but do not want to get another ISDN line
- at work. A router at the office location can manage a
- dedicated B channel connection (64&nbsp;Kbps) to the Internet
- and use the other B channel for a separate data connection.
- The second B channel can be used for dial-in, dial-out or
- dynamically bonding (MPP, etc.) with the first B channel for
- more bandwidth.</para>
-
- <indexterm><primary>IPX/SPX</primary></indexterm>
- <para>An Ethernet bridge will also allow you to transmit more
- than just IP traffic. You can also send IPX/SPX or whatever
- other protocols you use.</para>
- </sect2>
- </sect1>
-
<sect1 id="network-natd">
<sect1info>
<authorgroup>
@@ -5040,52 +4625,59 @@ ISDN BRI line</literallayout>
<title>Overview</title>
<indexterm>
- <primary><application>natd</application></primary>
+ <primary>&man.natd.8;</primary>
</indexterm>
- <para>FreeBSD's Network Address Translation daemon, commonly
- known as &man.natd.8; is a daemon that accepts incoming raw IP
- packets, changes the source to the local machine and
- re-injects these packets back into the outgoing IP packet
- stream. &man.natd.8; does this by changing the source IP
- address and port such that when data is received back, it is
- able to determine the original location of the data and
- forward it back to its original requester.</para>
+ <para>&os;'s Network Address Translation
+ (<acronym>NAT</acronym>) daemon, &man.natd.8;, accepts
+ incoming raw <acronym>IP</acronym> packets, changes the
+ source to the local machine, and injects these packets back
+ into the outgoing <acronym>IP</acronym> packet stream. The
+ source <acronym>IP</acronym> address and port are changed
+ such that when data is received back, it is able to determine
+ the original location of the data and forward it back to its
+ original requester.</para>
<indexterm>
<primary>Internet connection sharing</primary>
</indexterm>
<indexterm>
- <primary>NAT</primary>
+ <primary><acronym>NAT</acronym></primary>
</indexterm>
- <para>The most common use of NAT is to perform what is commonly
- known as Internet Connection Sharing.</para>
+ <para>The most common use of <acronym>NAT</acronym> is to
+ perform what is commonly known as Internet Connection
+ Sharing.</para>
</sect2>
<sect2 id="network-natsetup">
<title>Setup</title>
- <para>Due to the diminishing IP space in IPv4, and the increased
- number of users on high-speed consumer lines such as cable or
- DSL, people are increasingly in need of an Internet Connection
- Sharing solution. The ability to connect several computers
- online through one connection and IP address makes
- &man.natd.8; a reasonable choice.</para>
+ <para>Due to the diminishing <acronym>IP</acronym> address
+ space in <acronym>IPv4</acronym> and the increased number of
+ users on high-speed consumer lines such as cable or
+ <acronym>DSL</acronym>, people are increasingly in need of
+ an Internet Connection Sharing solution. The ability to
+ connect several computers online through one connection and
+ <acronym>IP</acronym> address makes &man.natd.8; a reasonable
+ choice.</para>
<para>Most commonly, a user has a machine connected to a cable
- or DSL line with one IP address and wishes to use this one
- connected computer to provide Internet access to several more
- over a LAN.</para>
-
- <para>To do this, the FreeBSD machine on the Internet must act
- as a gateway. This gateway machine must have two
- NICs&mdash;one for connecting to the Internet router, the
- other connecting to a LAN. All the machines on the LAN are
- connected through a hub or switch.</para>
+ or <acronym>DSL</acronym> line with one <acronym>IP</acronym>
+ address and wishes to use this one connected computer to
+ provide Internet access to several more over a
+ <acronym>LAN</acronym>.</para>
+
+ <para>To do this, the &os; machine connected to the Internet
+ must act as a gateway. This gateway machine must have two
+ <acronym>NIC</acronym>s: one connects to the Internet router
+ and the other connects to a <acronym>LAN</acronym>. All the
+ machines on the <acronym>LAN</acronym> are connected through
+ a hub or switch.</para>
<note>
- <para>There are many ways to get a LAN connected to the
- Internet through a &os; gateway. This example will only
- cover a gateway with at least two NICs.</para>
+ <para>There are many ways to get a <acronym>LAN</acronym>
+ connected to the Internet through a &os; gateway. This
+ example will only cover a gateway with at least two
+ <acronym>NIC</acronym>s.</para>
</note>
<mediaobject>
@@ -5112,7 +4704,7 @@ ISDN BRI line</literallayout>
<para>A setup like this is commonly used to share an Internet
connection. One of the <acronym>LAN</acronym> machines is
- connected to the Internet. The rest of the machines access
+ connected to the Internet and the rest of the machines access
the Internet through that <quote>gateway</quote>
machine.</para>
</sect2>
@@ -5125,10 +4717,9 @@ ISDN BRI line</literallayout>
<secondary>configuration</secondary>
</indexterm>
- <para>The kernel features for network address translation with
- &man.natd.8; are not enabled in the
- <filename>GENERIC</filename> kernel, but they can be preloaded
- at boot time, by adding a couple of options to
+ <para>The kernel features for &man.natd.8; are not enabled in
+ the <filename>GENERIC</filename> kernel, but they can be
+ loaded at boot time by adding a couple of options to
<filename>/boot/loader.conf</filename>:</para>
<programlisting>ipfw_load="YES"
@@ -5136,18 +4727,17 @@ ipdivert_load="YES"</programlisting>
<para>Additionally, the
<literal>net.inet.ip.fw.default_to_accept</literal> tunable
- option may be set to <literal>1</literal>:</para>
+ option should be set to <literal>1</literal>:</para>
<programlisting>net.inet.ip.fw.default_to_accept="1"</programlisting>
<note>
- <para>It is a very good idea to set this option during the
- first attempts to setup a firewall and NAT gateway. This
- way the default policy of &man.ipfw.8; will be
- <literal>allow ip from any to any</literal> instead of the
- less permissive <literal>deny ip from any to any</literal>,
- and it will be slightly more difficult to get locked out of
- the system right after a reboot.</para>
+ <para>It is a good idea to set this option during the first
+ attempts to setup a firewall and <acronym>NAT</acronym>
+ gateway. This sets the default policy of &man.ipfw.8; to
+ be more permissive than the default <literal>deny ip from
+ any to any</literal>, making it slightly more difficult
+ to get locked out of the system right after a reboot.</para>
</note>
</sect2>
@@ -5158,16 +4748,15 @@ ipdivert_load="YES"</programlisting>
<primary>kernel</primary>
<secondary>configuration</secondary>
</indexterm>
- <para>When modules are not an option or if it is preferrable to
- build all the required features into the running kernel, the
- following options must be in the kernel configuration
+ <para>When modules are not an option or if it is preferable to
+ build all the required features into a custom kernel, the
+ following options must be in the custom kernel configuration
file:</para>
<programlisting>options IPFIREWALL
options IPDIVERT</programlisting>
- <para>Additionally, at choice, the following may also be
- suitable:</para>
+ <para>Additionally, the following may also be suitable:</para>
<programlisting>options IPFIREWALL_DEFAULT_TO_ACCEPT
options IPFIREWALL_VERBOSE</programlisting>
@@ -5176,8 +4765,9 @@ options IPFIREWALL_VERBOSE</programlisting>
<sect2 id="network-natdsystemconfiguration">
<title>System Startup Configuration</title>
- <para>To enable firewall and NAT support at boot time, the
- following must be in <filename>/etc/rc.conf</filename>:</para>
+ <para>To enable firewall and <acronym>NAT</acronym> support at
+ boot time, the following must be in
+ <filename>/etc/rc.conf</filename>:</para>
<programlisting>gateway_enable="YES" <co id="co-natd-gateway-enable"/>
firewall_enable="YES" <co id="co-natd-firewall-enable"/>
@@ -5206,8 +4796,9 @@ natd_flags="" <co id="co-natd-natd-flags"/></programlisting>
</callout>
<callout arearefs="co-natd-natd-interface">
- <para>Indicates which interface to forward packets through
- (the interface connected to the Internet).</para>
+ <para>Indicates which interface to forward packets through.
+ This is the interface that is connected to the
+ Internet.</para>
</callout>
<callout arearefs="co-natd-natd-flags">
@@ -5216,10 +4807,10 @@ natd_flags="" <co id="co-natd-natd-flags"/></programlisting>
</callout>
</calloutlist>
- <para>Having the previous options defined in
- <filename>/etc/rc.conf</filename> would run
+ <para>These
+ <filename>/etc/rc.conf</filename> options will run
<command>natd -interface fxp0</command> at boot. This can
- also be run manually.</para>
+ also be run manually after boot.</para>
<note>
<para>It is also possible to use a configuration file for
@@ -5230,61 +4821,62 @@ natd_flags="" <co id="co-natd-natd-flags"/></programlisting>
<programlisting>natd_flags="-f /etc/natd.conf"</programlisting>
- <para>The <filename>/etc/natd.conf</filename> file will
- contain a list of configuration options, one per line. For
- example the next section case would use the following
- file:</para>
+ <para>A list of configuration options, one per line, can be
+ added to <filename>/etc/natd.conf</filename>. For
+ example:</para>
<programlisting>redirect_port tcp 192.168.0.2:6667 6667
redirect_port tcp 192.168.0.3:80 80</programlisting>
- <para>For more information about the configuration file,
- consult the &man.natd.8; manual page about the
- <option>-f</option> option.</para>
+ <para>For more information about this configuration file,
+ consult &man.natd.8;.</para>
</note>
- <para>Each machine and interface behind the LAN should be
- assigned IP address numbers in the private network space as
- defined by
- <ulink url="ftp://ftp.isi.edu/in-notes/rfc1918.txt">RFC
- 1918</ulink> and have a default gateway of the
- <application>natd</application> machine's internal IP
+ <para>Each machine and interface behind the
+ <acronym>LAN</acronym> should be assigned
+ <acronym>IP</acronym> addresses in the private network space,
+ as defined by <ulink
+ url="ftp://ftp.isi.edu/in-notes/rfc1918.txt">RFC
+ 1918</ulink>, and have a default gateway of the
+ &man.natd.8; machine's internal <acronym>IP</acronym>
address.</para>
<para>For example, client <hostid>A</hostid> and
- <hostid>B</hostid> behind the LAN have IP addresses of
- <hostid role="ipaddr">192.168.0.2</hostid> and
- <hostid role="ipaddr">192.168.0.3</hostid>, while the natd
- machine's LAN interface has an IP address of
- <hostid role="ipaddr">192.168.0.1</hostid>. Client
- <hostid>A</hostid> and <hostid>B</hostid>'s default gateway
- must be set to that of the <application>natd</application>
- machine, <hostid role="ipaddr">192.168.0.1</hostid>. The
- <application>natd</application> machine's external, or
- Internet interface does not require any special modification
- for &man.natd.8; to work.</para>
+ <hostid>B</hostid> behind the <acronym>LAN</acronym> have
+ <acronym>IP</acronym> addresses of <hostid
+ role="ipaddr">192.168.0.2</hostid> and <hostid
+ role="ipaddr">192.168.0.3</hostid>, while the &man.natd.8;
+ machine's <acronym>LAN</acronym> interface has an
+ <acronym>IP</acronym> address of <hostid
+ role="ipaddr">192.168.0.1</hostid>. The default gateway
+ of clients <hostid>A</hostid> and <hostid>B</hostid> must be
+ set to that of the &man.natd.8; machine, <hostid
+ role="ipaddr">192.168.0.1</hostid>. The &man.natd.8;
+ machine's external Internet interface does not require any
+ special modification for &man.natd.8; to work.</para>
</sect2>
<sect2 id="network-natdport-redirection">
<title>Port Redirection</title>
- <para>The drawback with &man.natd.8; is that the LAN clients are
- not accessible from the Internet. Clients on the LAN can make
+ <para>The drawback with &man.natd.8; is that the
+ <acronym>LAN</acronym> clients are not accessible from the
+ Internet. Clients on the <acronym>LAN</acronym> can make
outgoing connections to the world but cannot receive incoming
ones. This presents a problem if trying to run Internet
- services on one of the LAN client machines. A simple way
- around this is to redirect selected Internet ports on the
- <application>natd</application> machine to a LAN
+ services on one of the <acronym>LAN</acronym> client machines.
+ A simple way around this is to redirect selected Internet
+ ports on the &man.natd.8; machine to a <acronym>LAN</acronym>
client.</para>
- <para>For example, an IRC server runs on client
- <hostid>A</hostid>, and a web server runs on client
+ <para>For example, an <acronym>IRC</acronym> server runs on
+ client <hostid>A</hostid> and a web server runs on client
<hostid>B</hostid>. For this to work properly, connections
- received on ports 6667 (IRC) and 80 (web) must be redirected
- to the respective machines.</para>
+ received on ports 6667 (<acronym>IRC</acronym>) and 80
+ (<acronym>HTTP</acronym>) must be redirected to the
+ respective machines.</para>
- <para>The <option>-redirect_port</option> must be passed to
- &man.natd.8; with the proper options. The syntax is as
+ <para>The syntax for <option>-redirect_port</option> is as
follows:</para>
<programlisting> -redirect_port proto targetIP:targetPORT[-targetPORT]
@@ -5296,11 +4888,11 @@ redirect_port tcp 192.168.0.3:80 80</programlisting>
<programlisting> -redirect_port tcp 192.168.0.2:6667 6667
-redirect_port tcp 192.168.0.3:80 80</programlisting>
- <para>This will redirect the proper <emphasis>tcp</emphasis>
- ports to the LAN client machines.</para>
+ <para>This redirects the proper <acronym>TCP</acronym> ports
+ to the <acronym>LAN</acronym> client machines.</para>
- <para>The <option>-redirect_port</option> argument can be used
- to indicate port ranges over individual ports. For example,
+ <para>Port ranges over individual ports can be indicated with
+ <option>-redirect_port</option>. For example,
<replaceable>tcp 192.168.0.2:2000-3000 2000-3000</replaceable>
would redirect all connections received on ports 2000 to 3000
to ports 2000 to 3000 on client <hostid>A</hostid>.</para>
@@ -5319,23 +4911,26 @@ redirect_port tcp 192.168.0.3:80 80</programlisting>
<title>Address Redirection</title>
<indexterm><primary>address redirection</primary></indexterm>
- <para>Address redirection is useful if several IP addresses are
- available, yet they must be on one machine. With this,
- &man.natd.8; can assign each LAN client its own external IP
- address. &man.natd.8; then rewrites outgoing packets from the
- LAN clients with the proper external IP address and redirects
- all traffic incoming on that particular IP address back to the
- specific LAN client. This is also known as static NAT. For
- example, the IP addresses
- <hostid role="ipaddr">128.1.1.1</hostid>,
- <hostid role="ipaddr">128.1.1.2</hostid>, and
- <hostid role="ipaddr">128.1.1.3</hostid> belong to the
- <application>natd</application> gateway machine.
- <hostid role="ipaddr">128.1.1.1</hostid> can be used as the
- <application>natd</application> gateway machine's external IP
+ <para>Address redirection is useful if more than one
+ <acronym>IP</acronym> address is available. Each
+ <acronym>LAN</acronym> client can be assigned its own
+ external <acronym>IP</acronym> address by &man.natd.8;,
+ which will then rewrite outgoing packets from the
+ <acronym>LAN</acronym> clients with the proper external
+ <acronym>IP</acronym> address and redirects all traffic
+ incoming on that particular <acronym>IP</acronym> address
+ back to the specific <acronym>LAN</acronym> client. This is
+ also known as static <acronym>NAT</acronym>. For example,
+ if <acronym>IP</acronym> addresses <hostid
+ role="ipaddr">128.1.1.1</hostid>, <hostid
+ role="ipaddr">128.1.1.2</hostid>, and <hostid
+ role="ipaddr">128.1.1.3</hostid> are available, <hostid
+ role="ipaddr">128.1.1.1</hostid> can be used as the
+ &man.natd.8; machine's external <acronym>IP</acronym>
address, while <hostid role="ipaddr">128.1.1.2</hostid> and
- <hostid role="ipaddr">128.1.1.3</hostid> are forwarded back to
- LAN clients <hostid>A</hostid> and <hostid>B</hostid>.</para>
+ <hostid role="ipaddr">128.1.1.3</hostid> are forwarded back
+ to <acronym>LAN</acronym> clients <hostid>A</hostid> and
+ <hostid>B</hostid>.</para>
<para>The <option>-redirect_address</option> syntax is as
follows:</para>
@@ -5348,13 +4943,14 @@ redirect_port tcp 192.168.0.3:80 80</programlisting>
<tbody>
<row>
<entry>localIP</entry>
- <entry>The internal IP address of the LAN
- client.</entry>
+ <entry>The internal <acronym>IP</acronym> address of
+ the <acronym>LAN</acronym> client.</entry>
</row>
<row>
<entry>publicIP</entry>
- <entry>The external IP address corresponding to the LAN
+ <entry>The external <acronym>IP</acronym> address
+ corresponding to the <acronym>LAN</acronym>
client.</entry>
</row>
</tbody>
@@ -5367,16 +4963,16 @@ redirect_port tcp 192.168.0.3:80 80</programlisting>
-redirect_address 192.168.0.3 128.1.1.3</programlisting>
<para>Like <option>-redirect_port</option>, these arguments are
- also placed within the <literal>natd_flags=""</literal> option
+ placed within the <literal>natd_flags=""</literal> option
of <filename>/etc/rc.conf</filename>, or passed via a
configuration file. With address redirection, there is no
need for port redirection since all data received on a
- particular IP address is redirected.</para>
+ particular <acronym>IP</acronym> address is redirected.</para>
- <para>The external IP addresses on the
- <application>natd</application> machine must be active and
- aliased to the external interface. Look at &man.rc.conf.5; to
- do so.</para>
+ <para>The external <acronym>IP</acronym> addresses on the
+ &man.natd.8; machine must be active and aliased to the
+ external interface. Refer to &man.rc.conf.5; for
+ details.</para>
</sect2>
</sect1>
@@ -5405,29 +5001,32 @@ redirect_port tcp 192.168.0.3:80 80</programlisting>
</authorgroup>
</sect1info>
- <title>IPv6</title>
+ <title><acronym>IPv6</acronym></title>
- <para>IPv6 (also known as IPng <quote>IP next generation</quote>)
- is the new version of the well known IP protocol (also known as
- <acronym>IPv4</acronym>). Like the other current *BSD systems,
- FreeBSD includes the KAME IPv6 reference implementation. So
- your FreeBSD system comes with all you will need to experiment
- with IPv6. This section focuses on getting IPv6 configured and
- running.</para>
+ <para><acronym>IPv6</acronym>, also known as
+ <acronym>IPng</acronym> <quote><acronym>IP</acronym> next
+ generation</quote>, is the new version of the well known
+ <acronym>IP</acronym> protocol, also known as
+ <acronym>IPv4</acronym>. &os; includes the <ulink
+ url="http://www.kame.net/">KAME</ulink>
+ <acronym>IPv6</acronym> reference implementation. &os; comes
+ with everything needed to use <acronym>IPv6</acronym>. This
+ section focuses on getting <acronym>IPv6</acronym> configured
+ and running.</para>
<para>In the early 1990s, people became aware of the rapidly
- diminishing address space of IPv4. Given the expansion rate of
- the Internet there were two major concerns:</para>
+ diminishing address space of <acronym>IPv4</acronym>. Given
+ the expansion rate of the Internet, there were two major
+ concerns:</para>
<itemizedlist>
<listitem>
<para>Running out of addresses. Today this is not so much of
- a concern any more, since RFC1918 private address space
- (<hostid role="ipaddr">10.0.0.0/8</hostid>,
- <hostid role="ipaddr">172.16.0.0/12</hostid>, and
- <hostid role="ipaddr">192.168.0.0/16</hostid>) and Network
- Address Translation (<acronym>NAT</acronym>) are being
- employed.</para>
+ a concern, since RFC1918 private address space (<hostid
+ role="ipaddr">10.0.0.0/8</hostid>, <hostid
+ role="ipaddr">172.16.0.0/12</hostid>, and <hostid
+ role="ipaddr">192.168.0.0/16</hostid>) and
+ <acronym>NAT</acronym> are being employed.</para>
</listitem>
<listitem>
@@ -5436,57 +5035,59 @@ redirect_port tcp 192.168.0.3:80 80</programlisting>
</listitem>
</itemizedlist>
- <para>IPv6 deals with these and many other issues:</para>
+ <para><acronym>IPv6</acronym> deals with these and many other
+ issues by providing the following:</para>
<itemizedlist>
<listitem>
- <para>128 bit address space. In other words theoretically
- there are
+ <para>128 bit address space which allows for
340,282,366,920,938,463,463,374,607,431,768,211,456
- addresses available. This means there are approximately
- 6.67 * 10^27 IPv6 addresses per square meter on our
- planet.</para>
+ addresses. This means there are approximately
+ 6.67 * 10^27 <acronym>IPv6</acronym> addresses per square
+ meter on the planet.</para>
</listitem>
<listitem>
- <para>Routers will only store network aggregation addresses in
- their routing tables thus reducing the average space of a
+ <para>Routers only store network aggregation addresses in
+ their routing tables, thus reducing the average space of a
routing table to 8192 entries.</para>
</listitem>
</itemizedlist>
- <para>There are also lots of other useful features of IPv6 such
- as:</para>
+ <para>There are other useful features of
+ <acronym>IPv6</acronym>:</para>
<itemizedlist>
<listitem>
<para>Address autoconfiguration (<ulink
- url="http://www.ietf.org/rfc/rfc2462.txt">RFC2462</ulink>)</para>
+ url="http://www.ietf.org/rfc/rfc2462.txt">RFC2462</ulink>).</para>
</listitem>
<listitem>
<para>Anycast addresses (<quote>one-out-of
- many</quote>)</para>
+ many</quote>).</para>
</listitem>
<listitem>
- <para>Mandatory multicast addresses</para>
+ <para>Mandatory multicast addresses.</para>
</listitem>
<listitem>
- <para>IPsec (IP security)</para>
+ <para><acronym>IPsec</acronym> (<acronym>IP</acronym>
+ security).</para>
</listitem>
<listitem>
- <para>Simplified header structure</para>
+ <para>Simplified header structure.</para>
</listitem>
<listitem>
- <para>Mobile <acronym>IP</acronym></para>
+ <para>Mobile <acronym>IP</acronym>.</para>
</listitem>
<listitem>
- <para>IPv6-to-IPv4 transition mechanisms</para>
+ <para><acronym>IPv6</acronym>-to-<acronym>IPv4</acronym>
+ transition mechanisms.</para>
</listitem>
</itemizedlist>
@@ -5500,13 +5101,13 @@ redirect_port tcp 192.168.0.3:80 80</programlisting>
</itemizedlist>
<sect2>
- <title>Background on IPv6 Addresses</title>
+ <title>Background on <acronym>IPv6</acronym> Addresses</title>
- <para>There are different types of IPv6 addresses: Unicast,
- Anycast and Multicast.</para>
+ <para>There are different types of <acronym>IPv6</acronym>
+ addresses: unicast, anycast, and multicast.</para>
<para>Unicast addresses are the well known addresses. A packet
- sent to a unicast address arrives exactly at the interface
+ sent to a unicast address arrives at the interface
belonging to the address.</para>
<para>Anycast addresses are syntactically indistinguishable from
@@ -5520,18 +5121,18 @@ redirect_port tcp 192.168.0.3:80 80</programlisting>
interfaces belonging to the multicast group.</para>
<note>
- <para>The IPv4 broadcast address (usually
- <hostid role="ipaddr">xxx.xxx.xxx.255</hostid>) is expressed
- by multicast addresses in IPv6.</para>
+ <para>The <acronym>IPv4</acronym> broadcast address, usually
+ <hostid role="ipaddr">xxx.xxx.xxx.255</hostid>, is expressed
+ by multicast addresses in <acronym>IPv6</acronym>.</para>
</note>
<table frame="none">
- <title>Reserved IPv6 Addresses</title>
+ <title>Reserved <acronym>IPv6</acronym> Addresses</title>
<tgroup cols="4">
<thead>
<row>
- <entry>IPv6 address</entry>
+ <entry><acronym>IPv6</acronym> address</entry>
<entry>Prefixlength (Bits)</entry>
<entry>Description</entry>
<entry>Notes</entry>
@@ -5543,35 +5144,38 @@ redirect_port tcp 192.168.0.3:80 80</programlisting>
<entry><hostid role="ip6addr">::</hostid></entry>
<entry>128 bits</entry>
<entry>unspecified</entry>
- <entry>cf. <hostid role="ipaddr">0.0.0.0</hostid> in
- IPv4</entry>
+ <entry>Equivalent to <hostid
+ role="ipaddr">0.0.0.0</hostid> in
+ <acronym>IPv4</acronym>.</entry>
</row>
<row>
<entry><hostid role="ip6addr">::1</hostid></entry>
<entry>128 bits</entry>
<entry>loopback address</entry>
- <entry>cf. <hostid role="ipaddr">127.0.0.1</hostid> in
- IPv4</entry>
+ <entry>Equivalent to <hostid
+ role="ipaddr">127.0.0.1</hostid> in
+ <acronym>IPv4</acronym>.</entry>
</row>
<row>
<entry><hostid
role="ip6addr">::00:xx:xx:xx:xx</hostid></entry>
<entry>96 bits</entry>
- <entry>embedded IPv4</entry>
- <entry>The lower 32 bits are the IPv4 address. Also
- called <quote>IPv4 compatible IPv6
- address</quote></entry>
+ <entry>embedded <acronym>IPv4</acronym></entry>
+ <entry>The lower 32 bits are the compatible
+ <acronym>IPv4</acronym> address.</entry>
</row>
<row>
<entry><hostid
role="ip6addr">::ff:xx:xx:xx:xx</hostid></entry>
<entry>96 bits</entry>
- <entry>IPv4 mapped IPv6 address</entry>
- <entry>The lower 32 bits are the IPv4 address.
- For hosts which do not support IPv6.</entry>
+ <entry><acronym>IPv4</acronym> mapped
+ <acronym>IPv6</acronym> address</entry>
+ <entry>The lower 32 bits are the <acronym>IPv4</acronym>
+ address for hosts which do not support
+ <acronym>IPv6</acronym>.</entry>
</row>
<row>
@@ -5579,7 +5183,8 @@ redirect_port tcp 192.168.0.3:80 80</programlisting>
role="ip6addr">feb::</hostid></entry>
<entry>10 bits</entry>
<entry>link-local</entry>
- <entry>cf. loopback address in IPv4</entry>
+ <entry>Equivalent to the loopback address in
+ <acronym>IPv4</acronym>.</entry>
</row>
<row>
@@ -5612,34 +5217,32 @@ redirect_port tcp 192.168.0.3:80 80</programlisting>
</sect2>
<sect2>
- <title>Reading IPv6 Addresses</title>
+ <title>Reading <acronym>IPv6</acronym> Addresses</title>
<para>The canonical form is represented as:
- <hostid role="ip6addr">x:x:x:x:x:x:x:x</hostid>, each
- <quote>x</quote> being a 16 Bit hex value. For example
+ <hostid role="ip6addr">x:x:x:x:x:x:x:x</hostid>, with each
+ <quote>x</quote> being a 16 bit hex value. For example:
<hostid
- role="ip6addr">FEBC:A574:382B:23C1:AA49:4592:4EFE:9982</hostid></para>
+ role="ip6addr">FEBC:A574:382B:23C1:AA49:4592:4EFE:9982</hostid>.</para>
- <para>Often an address will have long substrings of all zeros
- therefore one such substring per address can be abbreviated by
- <quote>::</quote>. Also up to three leading <quote>0</quote>s
- per hexquad can be omitted. For example
+ <para>Often an address will have long substrings of all zeros.
+ One such substring per address can be abbreviated by
+ <quote>::</quote>. Also, up to three leading
+ <quote>0</quote>s per hex quad can be omitted. For example,
<hostid role="ip6addr">fe80::1</hostid> corresponds to the
canonical form <hostid
role="ip6addr">fe80:0000:0000:0000:0000:0000:0000:0001</hostid>.</para>
- <para>A third form is to write the last 32 Bit part in the
- well known (decimal) IPv4 style with dots <quote>.</quote>
- as separators. For example
- <hostid role="ip6addr">2002::10.0.0.1</hostid>
- corresponds to the (hexadecimal) canonical representation
- <hostid
- role="ip6addr">2002:0000:0000:0000:0000:0000:0a00:0001</hostid>
- which in turn is equivalent to writing
- <hostid role="ip6addr">2002::a00:1</hostid>.</para>
+ <para>A third form is to write the last 32 bit part in the
+ well known (decimal) <acronym>IPv4</acronym> style with dots
+ (<quote>.</quote>) as separators. For example, <hostid
+ role="ip6addr">2002::10.0.0.1</hostid> corresponds to the
+ hexadecimal canonical representation <hostid
+ role="ip6addr">2002:0000:0000:0000:0000:0000:0a00:0001</hostid>,
+ which in turn is equivalent to <hostid
+ role="ip6addr">2002::a00:1</hostid>.</para>
- <para>By now the reader should be able to understand the
- following:</para>
+ <para>Here is a sample entry from &man.ifconfig.8;:</para>
<screen>&prompt.root; <userinput>ifconfig</userinput></screen>
@@ -5651,25 +5254,26 @@ redirect_port tcp 192.168.0.3:80 80</programlisting>
status: active</programlisting>
<para><hostid
- role="ip6addr">fe80::200:21ff:fe03:8e1%rl0</hostid>
- is an auto configured link-local address. It is generated
- from the MAC address as part of the auto configuration.</para>
+ role="ip6addr">fe80::200:21ff:fe03:8e1%rl0</hostid> is an
+ auto configured link-local address. It is generated from
+ the <acronym>MAC</acronym> address as part of the auto
+ configuration.</para>
- <para>For further information on the structure of IPv6 addresses
- see <ulink
+ <para>For further information on the structure of
+ <acronym>IPv6</acronym> addresses, see <ulink
url="http://www.ietf.org/rfc/rfc3513.txt">RFC3513</ulink>.</para>
</sect2>
<sect2>
<title>Getting Connected</title>
- <para>Currently there are four ways to connect to other IPv6
- hosts and networks:</para>
+ <para>Currently, there are four ways to connect to other
+ <acronym>IPv6</acronym> hosts and networks:</para>
<itemizedlist>
<listitem>
- <para>Contact your Internet Service Provider to see if they
- offer IPv6 yet.</para>
+ <para>Contact an Internet Service Provider to see if they
+ offer <acronym>IPv6</acronym>.</para>
</listitem>
<listitem>
@@ -5678,37 +5282,36 @@ redirect_port tcp 192.168.0.3:80 80</programlisting>
</listitem>
<listitem>
- <para>Tunnel via 6-to-4 (<ulink
- url="http://www.ietf.org/rfc/rfc3068.txt">RFC3068</ulink>)</para>
+ <para>Tunnel via 6-to-4 as described in <ulink
+ url="http://www.ietf.org/rfc/rfc3068.txt">RFC3068</ulink>.</para>
</listitem>
<listitem>
<para>Use the
- <filename role="package">net/freenet6</filename> port if
- you are on a dial-up connection.</para>
+ <filename role="package">net/freenet6</filename> port
+ for a dial-up connection.</para>
</listitem>
</itemizedlist>
</sect2>
<sect2>
- <title>DNS in the IPv6 World</title>
+ <title><acronym>DNS</acronym> in the <acronym>IPv6</acronym>
+ World</title>
- <para>There used to be two types of DNS records for IPv6. The
- IETF has declared A6 records obsolete. AAAA records are the
- standard now.</para>
+ <para>There used to be two types of <acronym>DNS</acronym>
+ records for <acronym>IPv6</acronym>. The
+ <acronym>IETF</acronym> has declared <acronym>AAAA</acronym>
+ records as the current standard.</para>
- <para>Using AAAA records is straightforward. Assign your
- hostname to the new IPv6 address you just received by
- adding:</para>
+ <para>Using <acronym>AAAA</acronym> records is straightforward.
+ Assign the hostname to the <acronym>IPv6</acronym> address
+ in the primary zone <acronym>DNS</acronym> file:</para>
<programlisting>MYHOSTNAME AAAA MYIPv6ADDR</programlisting>
- <para>To your primary zone DNS file. In case you do not serve
- your own <acronym>DNS</acronym> zones ask your
- <acronym>DNS</acronym> provider. Current versions of
- <application>bind</application> (version 8.3 and 9) and
- <filename role="package">dns/djbdns</filename> (with the IPv6
- patch) support AAAA records.</para>
+ <para>Current versions of &man.named.8; and <filename
+ role="package">dns/djbdns</filename> support
+ <acronym>AAAA</acronym> records.</para>
</sect2>
<sect2>
@@ -5716,92 +5319,93 @@ redirect_port tcp 192.168.0.3:80 80</programlisting>
<filename>/etc/rc.conf</filename></title>
<sect3>
- <title>IPv6 Client Settings</title>
+ <title><acronym>IPv6</acronym> Client Settings</title>
- <para>These settings will help you configure a machine that
- will be on your LAN and act as a client, not a router. To
- have &man.rtsol.8; autoconfigure your interface on boot on
- &os;&nbsp;9.<replaceable>x</replaceable> and later,
- add:</para>
+ <para>These settings configure a machine on a
+ <acronym>LAN</acronym> which acts as a client, not a
+ router. To instruct &man.rtsol.8; to autoconfigure the
+ interface on boot on
+ &os;&nbsp;9.<replaceable>x</replaceable> and later, add
+ this line to <filename>rc.conf</filename>:</para>
<programlisting>ipv6_prefer="YES"</programlisting>
- <para>to <filename>rc.conf</filename>.</para>
-
- <para>For &os;&nbsp;8.<replaceable>x</replaceable> and
- earlier, add:</para>
+ <para>For &os;&nbsp;8.<replaceable>x</replaceable>,
+ add:</para>
<programlisting>ipv6_enable="YES"</programlisting>
- <para>To statically assign an IP address such as <hostid
+ <para>To statically assign the <acronym>IPv6</acronym>
+ address, <hostid
role="ip6addr">2001:471:1f11:251:290:27ff:fee0:2093</hostid>,
- to your <devicename>fxp0</devicename> interface, add the
- following for
+ to <devicename>fxp0</devicename>, add the following for
&os;&nbsp;9.<replaceable>x</replaceable>:</para>
<programlisting>ifconfig_fxp0_ipv6="inet6 2001:471:1f11:251:290:27ff:fee0:2093 prefixlen <replaceable>64</replaceable>"</programlisting>
<note>
<para>Be sure to change <replaceable>prefixlen
- 64</replaceable> to the appropriate value for the subnet
- within which the computer is networked.</para>
+ 64</replaceable> to the appropriate value for the
+ subnet.</para>
</note>
- <para>For &os;&nbsp;8<replaceable>x</replaceable> and earlier,
+ <para>For &os;&nbsp;8<replaceable>x</replaceable>,
add:</para>
<programlisting>ipv6_ifconfig_fxp0="2001:471:1f11:251:290:27ff:fee0:2093"</programlisting>
- <para>To assign a default router of
- <hostid role="ip6addr">2001:471:1f11:251::1</hostid> add the
+ <para>To assign a default router of <hostid
+ role="ip6addr">2001:471:1f11:251::1</hostid>, add the
following to <filename>/etc/rc.conf</filename>:</para>
<programlisting>ipv6_defaultrouter="2001:471:1f11:251::1"</programlisting>
</sect3>
<sect3>
- <title>IPv6 Router/Gateway Settings</title>
+ <title><acronym>IPv6</acronym> Router/Gateway Settings</title>
- <para>This will help you take the directions that your tunnel
- provider has given you and convert it into settings that
- will persist through reboots. To restore your tunnel on
- startup use something like the following in
- <filename>/etc/rc.conf</filename>:</para>
+ <para>This section demonstrates how to take the directions
+ from a tunnel provider and convert it into settings that
+ will persist through reboots. To restore the tunnel on
+ startup, add the following lines to
+ <filename>/etc/rc.conf</filename>.</para>
- <para>List the Generic Tunneling interfaces that will be
- configured, for example
+ <para>The first entry lists the generic tunneling interfaces
+ to be configured. This example configures one interface,
<devicename>gif0</devicename>:</para>
<programlisting>gif_interfaces="gif0"</programlisting>
- <para>To configure the interface with a local endpoint of
+ <para>To configure that interface with a local endpoint of
<replaceable>MY_IPv4_ADDR</replaceable> to a remote endpoint
of <replaceable>REMOTE_IPv4_ADDR</replaceable>:</para>
<programlisting>gifconfig_gif0="<replaceable>MY_IPv4_ADDR REMOTE_IPv4_ADDR</replaceable>"</programlisting>
- <para>To apply the IPv6 address you have been assigned for use
- as your IPv6 tunnel endpoint, add the following for
+ <para>To apply the <acronym>IPv6</acronym> address that has
+ been assigned for use as the <acronym>IPv6</acronym> tunnel
+ endpoint, add the following line for
&os;&nbsp;9.<replaceable>x</replaceable> and later:</para>
<programlisting>ifconfig_gif0_ipv6="inet6 <replaceable>MY_ASSIGNED_IPv6_TUNNEL_ENDPOINT_ADDR</replaceable>"</programlisting>
- <para>For &os;&nbsp;8.<replaceable>x</replaceable> and
- earlier, add:</para>
+ <para>For &os;&nbsp;8.<replaceable>x</replaceable>,
+ add:</para>
<programlisting>ipv6_ifconfig_gif0="<replaceable>MY_ASSIGNED_IPv6_TUNNEL_ENDPOINT_ADDR</replaceable>"</programlisting>
- <para>Then all you have to do is set the default route for
- IPv6. This is the other side of the IPv6 tunnel:</para>
+ <para>Then, set the default route for
+ <acronym>IPv6</acronym>. This is the other side of the
+ <acronym>IPv6</acronym> tunnel:</para>
<programlisting>ipv6_defaultrouter="<replaceable>MY_IPv6_REMOTE_TUNNEL_ENDPOINT_ADDR</replaceable>"</programlisting>
</sect3>
<sect3>
- <title>IPv6 Tunnel Settings</title>
+ <title><acronym>IPv6</acronym> Tunnel Settings</title>
- <para>If the server is to route IPv6 between the rest of your
- network and the world, the following
+ <para>If the server is to route <acronym>IPv6</acronym>
+ between the rest of the network and the world, the following
<filename>/etc/rc.conf</filename> setting will also be
needed:</para>
@@ -5812,38 +5416,65 @@ redirect_port tcp 192.168.0.3:80 80</programlisting>
<sect2>
<title>Router Advertisement and Host Auto Configuration</title>
- <para>This section will help you setup &man.rtadvd.8; to
- advertise the IPv6 default route.</para>
+ <para>This section demonstrates how to setup &man.rtadvd.8; to
+ advertise the <acronym>IPv6</acronym> default route.</para>
- <para>To enable &man.rtadvd.8; you will need the following in
- your <filename>/etc/rc.conf</filename>:</para>
+ <para>To enable &man.rtadvd.8;, add the following to
+ <filename>/etc/rc.conf</filename>:</para>
<programlisting>rtadvd_enable="YES"</programlisting>
- <para>It is important that you specify the interface on which to
- do IPv6 router solicitation. For example to tell
- &man.rtadvd.8; to use <devicename>fxp0</devicename>:</para>
+ <para>It is important to specify the interface on which to
+ do <acronym>IPv6</acronym> router solicitation. For example,
+ to tell &man.rtadvd.8; to use
+ <devicename>fxp0</devicename>:</para>
<programlisting>rtadvd_interfaces="fxp0"</programlisting>
- <para>Now we must create the configuration file,
- <filename>/etc/rtadvd.conf</filename>. Here is an
+ <para>Next, create the configuration file,
+ <filename>/etc/rtadvd.conf</filename> as seen in this
example:</para>
<programlisting>fxp0:\
:addrs#1:addr="2001:471:1f11:246::":prefixlen#64:tc=ether:</programlisting>
<para>Replace <devicename>fxp0</devicename> with the interface
- you are going to be using.</para>
+ to be used and <hostid
+ role="ip6addr">2001:471:1f11:246::</hostid> with the
+ prefix of the allocation.</para>
- <para>Next, replace
- <hostid role="ip6addr">2001:471:1f11:246::</hostid> with the
- prefix of your allocation.</para>
+ <para>For a dedicated <hostid role="netmask">/64</hostid>
+ subnet, nothing else needs to be changed. Otherwise, change
+ the <literal>prefixlen#</literal> to the correct value.</para>
+ </sect2>
- <para>If you are dedicated a <hostid role="netmask">/64</hostid>
- subnet you will not need to change anything else. Otherwise,
- you will need to change the <literal>prefixlen#</literal> to
- the correct value.</para>
+ <sect2>
+ <title><acronym>IPv6</acronym> and <acronym>IPv6</acronym>
+ Address Mapping</title>
+
+ <para>When <acronym>IPv6</acronym> is enabled on a server, there
+ may be a need to enable <acronym>IPv4</acronym> mapped
+ <acronym>IPv6</acronym> address communication. This
+ compatibility option allows for <acronym>IPv4</acronym>
+ addresses to be represented as <acronym>IPv6</acronym>
+ addresses. Permitting <acronym>IPv6</acronym> applications
+ to communicate with <acronym>IPv4</acronym> and vice versa
+ may be a security issue.</para>
+
+ <para>This option may not be required in most cases and is
+ available only for compatibility. This option will allow
+ <acronym>IPv6</acronym>-only applications to work with
+ <acronym>IPv4</acronym> in a dual stack environment. This
+ is most useful for third party applications which may not
+ support an <acronym>IPv6</acronym>-only environment. To
+ enable this feature,
+ add the following to <filename>/etc/rc.conf</filename>:</para>
+
+ <programlisting>ipv6_ipv4mapping="YES"</programlisting>
+
+ <para>Reviewing the information in <acronym>RFC</acronym> 3493,
+ section 3.6 and 3.7 as well as <acronym>RFC</acronym> 4038
+ section 4.2 may be useful to some adminstrators.</para>
</sect2>
</sect1>
@@ -5858,34 +5489,38 @@ redirect_port tcp 192.168.0.3:80 80</programlisting>
</authorgroup>
</sect1info>
- <title>Asynchronous Transfer Mode (ATM)</title>
+ <title>Asynchronous Transfer Mode (<acronym>ATM</acronym>)</title>
<sect2>
- <title>Configuring Classical IP over ATM (PVCs)</title>
-
- <para>Classical IP over ATM (<acronym>CLIP</acronym>) is the
- simplest method to use Asynchronous Transfer Mode (ATM)
- with IP. It can be used with
- switched connections (SVCs) and with permanent connections
- (PVCs). This section describes how to set up a network based
- on PVCs.</para>
+ <title>Configuring Classical <acronym>IP</acronym> over
+ <acronym>ATM</acronym></title>
+
+ <para>Classical <acronym>IP</acronym> over
+ <acronym>ATM</acronym> (<acronym>CLIP</acronym>) is the
+ simplest method to use Asynchronous Transfer Mode
+ (<acronym>ATM</acronym>) with <acronym>IP</acronym>. It can
+ be used with Switched Virtual Circuits
+ (<acronym>SVC</acronym>s) and with Permanent Virtual Circuits
+ (<acronym>PVC</acronym>s). This section describes how to
+ set up a network based on <acronym>PVC</acronym>s.</para>
<sect3>
<title>Fully Meshed Configurations</title>
<para>The first method to set up a <acronym>CLIP</acronym>
- with PVCs is to connect each machine to each other machine
- in the network via a dedicated PVC. While this is simple to
- configure it tends to become impractical for a larger number
- of machines. The example supposes that we have four
- machines in the network, each connected to the
- <acronym role="Asynchronous Transfer Mode">ATM</acronym>
- network with an
- <acronym role="Asynchronous Transfer Mode">ATM</acronym>
- adapter card. The first step is the planning of the IP
- addresses and the
- <acronym role="Asynchronous Transfer Mode">ATM</acronym>
- connections between the machines. We use the
+ with <acronym>PVC</acronym>s is to connect each machine
+ to each other machine in the network via a dedicated
+ <acronym>PVC</acronym>. While this is simple to
+ configure, it becomes impractical for a large number of
+ machines. The following example supposes four machines in
+ the network, each connected to the <acronym
+ role="Asynchronous Transfer Mode">ATM</acronym> network
+ with an <acronym
+ role="Asynchronous Transfer Mode">ATM</acronym> adapter
+ card. The first step is the planning of the
+ <acronym>IP</acronym> addresses and the <acronym
+ role="Asynchronous Transfer Mode">ATM</acronym>
+ connections between the machines. This example uses the
following:</para>
<informaltable frame="none" pgwide="1">
@@ -5895,7 +5530,7 @@ redirect_port tcp 192.168.0.3:80 80</programlisting>
<thead>
<row>
<entry>Host</entry>
- <entry>IP Address</entry>
+ <entry><acronym>IP</acronym> Address</entry>
</row>
</thead>
@@ -5927,8 +5562,8 @@ redirect_port tcp 192.168.0.3:80 80</programlisting>
</tgroup>
</informaltable>
- <para>To build a fully meshed net we need one ATM connection
- between each pair of machines:</para>
+ <para>To build a fully meshed net, one <acronym>ATM</acronym>
+ connection is needed between each pair of machines:</para>
<informaltable frame="none" pgwide="1">
<tgroup cols="2">
@@ -5981,22 +5616,24 @@ redirect_port tcp 192.168.0.3:80 80</programlisting>
</tgroup>
</informaltable>
- <para>The VPI and VCI values at each end of the connection may
- of course differ, but for simplicity we assume that they are
- the same. Next we need to configure the ATM interfaces on
- each host:</para>
+ <para>The Virtual Path Identifier <acronym>VPI</acronym> and
+ Virtual Channel Identifier <acronym>VCI</acronym> values
+ at each end of the connection may differ, but for
+ simplicity, this example assumes they are the same. Next,
+ configure the <acronym>ATM</acronym> interfaces on each
+ host:</para>
<screen>hostA&prompt.root; <userinput>ifconfig hatm0 192.168.173.1 up</userinput>
hostB&prompt.root; <userinput>ifconfig hatm0 192.168.173.2 up</userinput>
hostC&prompt.root; <userinput>ifconfig hatm0 192.168.173.3 up</userinput>
hostD&prompt.root; <userinput>ifconfig hatm0 192.168.173.4 up</userinput></screen>
- <para>assuming that the ATM interface is
- <devicename>hatm0</devicename> on all hosts. Now the PVCs
- need to be configured on <hostid>hostA</hostid> (we assume
- that they are already configured on the ATM switches, you
- need to consult the manual for the switch on how to do
- this).</para>
+ <para>This example assumes that the <acronym>ATM</acronym>
+ interface is <devicename>hatm0</devicename> on all hosts.
+ Next, the <acronym>PVC</acronym>s need to be configured on
+ <hostid>hostA</hostid>. This should already be configured
+ on the <acronym>ATM</acronym> switch; consult the manual
+ for the switch on how to do this.</para>
<screen>hostA&prompt.root; <userinput>atmconfig natm add 192.168.173.2 hatm0 0 100 llc/snap ubr</userinput>
hostA&prompt.root; <userinput>atmconfig natm add 192.168.173.3 hatm0 0 101 llc/snap ubr</userinput>
@@ -6014,19 +5651,19 @@ hostD&prompt.root; <userinput>atmconfig natm add 192.168.173.1 hatm0 0 102 llc/s
hostD&prompt.root; <userinput>atmconfig natm add 192.168.173.2 hatm0 0 104 llc/snap ubr</userinput>
hostD&prompt.root; <userinput>atmconfig natm add 192.168.173.3 hatm0 0 105 llc/snap ubr</userinput></screen>
- <para>Of course other traffic contracts than UBR can be used
- given the ATM adapter supports those. In this case the name
- of the traffic contract is followed by the parameters of the
- traffic. Help for the &man.atmconfig.8; tool can be
- obtained with:</para>
+ <para>Other traffic contracts besides <literal>ubr</literal>
+ can be used if the <acronym>ATM</acronym> adapter supports
+ it. In this case, the name of the traffic contract is
+ followed by the parameters of the traffic. Help for the
+ &man.atmconfig.8; tool can be obtained with:</para>
<screen>&prompt.root; <userinput>atmconfig help natm add</userinput></screen>
- <para>or in the &man.atmconfig.8; manual page.</para>
+ <para>Refer to &man.atmconfig.8; for more information.</para>
<para>The same configuration can also be done via
- <filename>/etc/rc.conf</filename>. For
- <hostid>hostA</hostid> this would look like:</para>
+ <filename>/etc/rc.conf</filename>. These lines configure
+ <hostid>hostA</hostid>:</para>
<programlisting>network_interfaces="lo0 hatm0"
ifconfig_hatm0="inet 192.168.173.1 up"
@@ -6054,37 +5691,38 @@ route_hostD="192.168.173.4 hatm0 0 102 llc/snap ubr"</programlisting>
</authorgroup>
</sect1info>
- <title>Common Address Redundancy Protocol (CARP)</title>
+ <title>Common Address Redundancy Protocol
+ (<acronym>CARP</acronym>)</title>
<indexterm>
- <primary>CARP</primary>
+ <primary><acronym>CARP</acronym></primary>
</indexterm>
<indexterm>
<primary>Common Address Redundancy Protocol</primary>
</indexterm>
- <para>The Common Address Redundancy Protocol, or
- <acronym>CARP</acronym> allows multiple hosts to share the same
- <acronym>IP</acronym> address. In some configurations, this may
- be used for availability or load balancing. Hosts may use
- separate <acronym>IP</acronym> addresses as well, as in the
+ <para>The Common Address Redundancy Protocol
+ (<acronym>CARP</acronym>) allows multiple hosts to share the
+ same <acronym>IP</acronym> address. In some configurations,
+ this may be used for availability or load balancing. Hosts
+ may use separate <acronym>IP</acronym> addresses, as in the
example provided here.</para>
<para>To enable support for <acronym>CARP</acronym>, the &os;
- kernel must be rebuilt as described in
- <xref linkend="kernelconfig"/> with the following option:</para>
+ kernel can be rebuilt as described in <xref
+ linkend="kernelconfig"/> with the following option:</para>
<programlisting>device carp</programlisting>
<para>Alternatively, the <filename>if_carp.ko</filename> module
- can be loaded at boot time. Add the following line to the
+ can be loaded at boot time. Add the following line to
<filename>/boot/loader.conf</filename>:</para>
<programlisting>if_carp_load="YES"</programlisting>
<para><acronym>CARP</acronym> functionality should now be
- available and may be tuned via several <command>sysctl</command>
- <acronym>OID</acronym>s:</para>
+ available and may be tuned via several &man.sysctl.8;
+ variables:</para>
<informaltable frame="none" pgwide="1">
<tgroup cols="2">
@@ -6106,15 +5744,15 @@ route_hostD="192.168.173.4 hatm0 0 102 llc/snap ubr"</programlisting>
<entry><varname>net.inet.carp.preempt</varname></entry>
<entry>This option downs all of the
<acronym>CARP</acronym> interfaces on the host when one
- of them goes down. Disabled by default</entry>
+ goes down. Disabled by default.</entry>
</row>
<row>
<entry><varname>net.inet.carp.log</varname></entry>
<entry>A value of <literal>0</literal> disables any
- logging. A Value of <literal>1</literal> enables
+ logging. A value of <literal>1</literal> enables
logging of bad <acronym>CARP</acronym> packets. Values
- greater than <literal>1</literal> enables logging of
+ greater than <literal>1</literal> enable logging of
state changes for the <acronym>CARP</acronym>
interfaces. The default value is
<literal>1</literal>.</entry>
@@ -6128,63 +5766,64 @@ route_hostD="192.168.173.4 hatm0 0 102 llc/snap ubr"</programlisting>
<row>
<entry><varname>net.inet.carp.suppress_preempt</varname></entry>
- <entry>A read only <acronym>OID</acronym> showing the
- status of preemption suppression. Preemption can be
- suppressed if link on an interface is down. A value of
- <literal>0</literal>, means that preemption is not
+ <entry>A read-only variable showing the status of
+ preemption suppression. Preemption can be suppressed
+ if the link on an interface is down. A value of
+ <literal>0</literal> means that preemption is not
suppressed. Every problem increments this
- <acronym>OID</acronym>.</entry>
+ variable.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>The <acronym>CARP</acronym> devices themselves may be
- created via the <command>ifconfig</command> command:</para>
+ created using &man.ifconfig.8;:</para>
<screen>&prompt.root; <userinput>ifconfig carp0 create</userinput></screen>
- <para>In a real environment, these interfaces will need unique
- identification numbers known as a <acronym>VHID</acronym>. This
- <acronym>VHID</acronym> or Virtual Host Identification will be
- used to distinguish the host on the network.</para>
+ <para>In a real environment, each interface has a unique
+ identification number known as a Virtual Host IDentification
+ (<acronym>VHID</acronym>) which is used to distinguish the
+ host on the network.</para>
<sect2>
- <title>Using CARP for Server Availability (CARP)</title>
+ <title>Using <acronym>CARP</acronym> for Server
+ Availability</title>
- <para>One use of <acronym>CARP</acronym>, as noted above, is for
- server availability. This example will provide failover
- support for three hosts, all with unique <acronym>IP</acronym>
+ <para>One use of <acronym>CARP</acronym> is to provide server
+ availability. This example configures failover support for
+ three hosts, all with unique <acronym>IP</acronym>
addresses and providing the same web content. These machines
- will act in conjunction with a Round Robin
+ act in conjunction with a Round Robin
<acronym>DNS</acronym> configuration. The failover machine
- will have two additional <acronym>CARP</acronym> interfaces,
- one for each of the content server's <acronym>IP</acronym>s.
- When a failure occurs, the failover server should pick up the
- failed machine's <acronym>IP</acronym> address. This means
- the failure should go completely unnoticed to the user. The
- failover server requires identical content and services as the
- other content servers it is expected to pick up load
- for.</para>
+ has two additional <acronym>CARP</acronym> interfaces, one
+ for each of the content server's
+ <acronym>IP</acronym> addresses. When a
+ failure occurs, the failover server will pick up the failed
+ machine's <acronym>IP</acronym> address.
+ This means that the failure should go completely unnoticed
+ by the user. The failover server requires identical content
+ and services as the other content servers it is expected to
+ pick up load for.</para>
<para>The two machines should be configured identically other
- than their issued hostnames and <acronym>VHID</acronym>s.
- This example calls these machines
+ than their hostnames and <acronym>VHID</acronym>s. This
+ example calls these machines
<hostid>hosta.example.org</hostid> and
<hostid>hostb.example.org</hostid> respectively. First, the
required lines for a <acronym>CARP</acronym> configuration
- have to be added to <filename>rc.conf</filename>. For
- <hostid>hosta.example.org</hostid>, the
- <filename>rc.conf</filename> file should contain the following
- lines:</para>
+ have to be added to <filename>/etc/rc.conf</filename>. Here
+ are the lines for
+ <hostid>hosta.example.org</hostid>:</para>
<programlisting>hostname="hosta.example.org"
ifconfig_fxp0="inet 192.168.1.3 netmask 255.255.255.0"
cloned_interfaces="carp0"
ifconfig_carp0="vhid 1 pass testpass 192.168.1.50/24"</programlisting>
- <para>On <hostid>hostb.example.org</hostid> the following lines
- should be in <filename>rc.conf</filename>:</para>
+ <para>On <hostid>hostb.example.org</hostid>, use the following
+ lines:</para>
<programlisting>hostname="hostb.example.org"
ifconfig_fxp0="inet 192.168.1.4 netmask 255.255.255.0"
@@ -6193,19 +5832,18 @@ ifconfig_carp0="vhid 2 pass testpass 192.168.1.51/24"</programlisting>
<note>
<para>It is very important that the passwords, specified by
- the <option>pass</option> option to
- <command>ifconfig</command>, are identical. The
- <devicename>carp</devicename> devices will only listen to
- and accept advertisements from machines with the correct
- password. The <acronym>VHID</acronym> must also be
- different for each machine.</para>
+ the <option>pass</option> option to &man.ifconfig.8;, are
+ identical. The <devicename>carp</devicename> devices will
+ only listen to and accept advertisements from machines
+ with the correct password. The <acronym>VHID</acronym>
+ must also be unique for each machine.</para>
</note>
<para>The third machine, <hostid>provider.example.org</hostid>,
should be prepared so that it may handle failover from either
host. This machine will require two
<devicename>carp</devicename> devices, one to handle each
- host. The appropriate <filename>rc.conf</filename>
+ host. The appropriate <filename>/etc/rc.conf</filename>
configuration lines will be similar to the following:</para>
<programlisting>hostname="provider.example.org"
@@ -6216,7 +5854,7 @@ ifconfig_carp1="vhid 2 advskew 100 pass testpass 192.168.1.51/24"</programlistin
<para>Having the two <devicename>carp</devicename> devices will
allow <hostid>provider.example.org</hostid> to notice and pick
- up the <acronym>IP</acronym> address of either machine should
+ up the <acronym>IP</acronym> address of either machine, should
it stop responding.</para>
<note>
@@ -6225,8 +5863,8 @@ ifconfig_carp1="vhid 2 advskew 100 pass testpass 192.168.1.51/24"</programlistin
<hostid>provider.example.org</hostid> may not relinquish the
<acronym>IP</acronym> address back to the original content
server. In this case, an administrator may have to manually
- force the IP back to the master. The following command
- should be issued on
+ force the <acronym>IP</acronym> back to the master. The
+ following command should be issued on
<hostid>provider.example.org</hostid>:</para>
<screen>&prompt.root; <userinput>ifconfig carp0 down &amp;&amp; ifconfig carp0 up</userinput></screen>
@@ -6235,13 +5873,11 @@ ifconfig_carp1="vhid 2 advskew 100 pass testpass 192.168.1.51/24"</programlistin
interface which corresponds to the correct host.</para>
</note>
- <para>At this point, <acronym>CARP</acronym> should be
- completely enabled and available for testing. For testing,
- either networking has to be restarted or the machines need to
- be rebooted.</para>
+ <para>At this point, <acronym>CARP</acronym> should be enabled
+ and available for testing. For testing, either networking
+ has to be restarted or the machines rebooted.</para>
- <para>More information is always available in the &man.carp.4;
- manual page.</para>
+ <para>More information is available in &man.carp.4;.</para>
</sect2>
</sect1>
</chapter>
diff --git a/en_US.ISO8859-1/books/handbook/audit/chapter.xml b/en_US.ISO8859-1/books/handbook/audit/chapter.xml
index 5d5540e5f6..e666e6a91e 100644
--- a/en_US.ISO8859-1/books/handbook/audit/chapter.xml
+++ b/en_US.ISO8859-1/books/handbook/audit/chapter.xml
@@ -60,8 +60,8 @@ requirements. -->
</listitem>
<listitem>
- <para>How to configure Event Auditing on &os; for users
- and processes.</para>
+ <para>How to configure Event Auditing on &os; for users and
+ processes.</para>
</listitem>
<listitem>
@@ -85,8 +85,8 @@ requirements. -->
</listitem>
<listitem>
- <para>Have some familiarity with security and how it
- pertains to &os; (<xref linkend="security"/>).</para>
+ <para>Have some familiarity with security and how it pertains
+ to &os; (<xref linkend="security"/>).</para>
</listitem>
</itemizedlist>
@@ -104,9 +104,9 @@ requirements. -->
Administrators should take into account disk space
requirements associated with high volume audit configurations.
For example, it may be desirable to dedicate a file system to
- the <filename class="directory">/var/audit</filename> tree so that other file
- systems are not affected if the audit file system becomes
- full.</para>
+ the <filename class="directory">/var/audit</filename> tree
+ so that other file systems are not affected if the audit file
+ system becomes full.</para>
</warning>
</sect1>
@@ -133,9 +133,9 @@ requirements. -->
<listitem>
<para><emphasis>class</emphasis>: Event classes are named sets
of related events, and are used in selection expressions.
- Commonly used classes of events include
- <quote>file creation</quote> (fc), <quote>exec</quote> (ex)
- and <quote>login_logout</quote> (lo).</para>
+ Commonly used classes of events include <quote>file
+ creation</quote> (fc), <quote>exec</quote> (ex) and
+ <quote>login_logout</quote> (lo).</para>
</listitem>
<listitem>
@@ -199,8 +199,8 @@ requirements. -->
<programlisting>options AUDIT</programlisting>
<para>Rebuild and reinstall
- the kernel via the normal process explained in
- <xref linkend="kernelconfig"/>.</para>
+ the kernel via the normal process explained in <xref
+ linkend="kernelconfig"/>.</para>
<para>Once an audit-enabled kernel is built, installed, and the
system has been rebooted, enable the audit daemon by adding the
@@ -249,10 +249,10 @@ requirements. -->
<listitem>
<para><filename>audit_warn</filename> - A customizable shell
- script used by <application>auditd</application> to generate
- warning messages in exceptional situations, such as when
- space for audit records is running low or when the audit
- trail file has been rotated.</para>
+ script used by &man.auditd.8; to generate warning messages
+ in exceptional situations, such as when space for audit
+ records is running low or when the audit trail file has
+ been rotated.</para>
</listitem>
</itemizedlist>
@@ -400,8 +400,8 @@ requirements. -->
</itemizedlist>
<para>These audit event classes may be customized by modifying
- the <filename>audit_class</filename> and
- <filename>audit_event</filename> configuration files.</para>
+ the <filename>audit_class</filename> and <filename>audit_
+ event</filename> configuration files.</para>
<para>Each audit class in the list is combined with a prefix
indicating whether successful/failed operations are matched,
@@ -451,18 +451,16 @@ requirements. -->
<title>Configuration Files</title>
<para>In most cases, administrators will need to modify only two
- files when configuring the audit system:
- <filename>audit_control</filename> and
- <filename>audit_user</filename>. The first controls
- system-wide audit properties and policies; the second may be
- used to fine-tune auditing by user.</para>
+ files when configuring the audit system: <filename>audit_
+ control</filename> and <filename>audit_user</filename>.
+ The first controls system-wide audit properties and policies;
+ the second may be used to fine-tune auditing by user.</para>
<sect3 id="audit-auditcontrol">
<title>The <filename>audit_control</filename> File</title>
- <para>The <filename>audit_control</filename> file specifies a
- number of defaults for the audit subsystem. Viewing the
- contents of this file, we see the following:</para>
+ <para>A number of defaults for the audit subsystem are
+ specified in <filename>audit_control</filename>:</para>
<programlisting>dir:/var/audit
flags:lo
@@ -471,7 +469,7 @@ naflags:lo
policy:cnt
filesz:0</programlisting>
- <para>The <option>dir</option> option is used to set one or
+ <para>The <option>dir</option> entry is used to set one or
more directories where audit logs will be stored. If more
than one directory entry appears, they will be used in order
as they fill. It is common to configure audit so that audit
@@ -484,17 +482,17 @@ filesz:0</programlisting>
example above, successful and failed login and logout events
are audited for all users.</para>
- <para>The <option>minfree</option> option defines the minimum
+ <para>The <option>minfree</option> entry defines the minimum
percentage of free space for the file system where the audit
trail is stored. When this threshold is exceeded, a warning
will be generated. The above example sets the minimum free
space to twenty percent.</para>
- <para>The <option>naflags</option> option specifies audit
- classes to be audited for non-attributed events, such as the
- login process and system daemons.</para>
+ <para>The <option>naflags</option> entry specifies audit classes
+ to be audited for non-attributed events, such as the login
+ process and system daemons.</para>
- <para>The <option>policy</option> option specifies a
+ <para>The <option>policy</option> entry specifies a
comma-separated list of policy flags controlling various
aspects of audit behavior. The default
<literal>cnt</literal> flag indicates that the system should
@@ -504,7 +502,7 @@ filesz:0</programlisting>
to the &man.execve.2; system call to be audited as part of
command execution.</para>
- <para>The <option>filesz</option> option specifies the maximum
+ <para>The <option>filesz</option> entry specifies the maximum
size in bytes to allow an audit trail file to grow to before
automatically terminating and rotating the trail file. The
default, 0, disables automatic log rotation. If the
@@ -516,25 +514,24 @@ filesz:0</programlisting>
<sect3 id="audit-audituser">
<title>The <filename>audit_user</filename> File</title>
- <para>The <filename>audit_user</filename> file permits the
- administrator to specify further audit requirements for
- specific users. Each line configures auditing for a user
- via two fields: the first is the
- <literal>alwaysaudit</literal> field, which specifies a set
- of events that should always be audited for the user, and
- the second is the <literal>neveraudit</literal> field, which
- specifies a set of events that should never be audited for
- the user.</para>
+ <para>The administrator can specify further audit requirements
+ for specific users in <filename>audit_user</filename>.
+ Each line configures auditing for a user via two fields:
+ the first is the <literal>alwaysaudit</literal> field,
+ which specifies a set of events that should always be
+ audited for the user, and the second is the
+ <literal>neveraudit</literal> field, which specifies a set
+ of events that should never be audited for the user.</para>
<para>The following example <filename>audit_user</filename>
- file audits login/logout events and successful command
- execution for the <username>root</username> user, and audits
- file creation and successful command execution for the
- <username>www</username> user. If used with the example
- <filename>audit_control</filename> file above, the
+ audits login/logout events and successful command
+ execution for <username>root</username>, and audits
+ file creation and successful command execution for
+ <username>www</username>. If used with the above example
+ <filename>audit_control</filename>, the
<literal>lo</literal> entry for <username>root</username> is
redundant, and login/logout events will also be audited for
- the <username>www</username> user.</para>
+ <username>www</username>.</para>
<programlisting>root:lo,+ex:no
www:fc,+ex:no</programlisting>
@@ -553,14 +550,13 @@ www:fc,+ex:no</programlisting>
&man.praudit.1; command converts trail files to a simple text
format; the &man.auditreduce.1; command may be used to reduce
the audit trail file for analysis, archiving, or printing
- purposes. <command>auditreduce</command> supports a variety
- of selection parameters, including event type, event class,
+ purposes. A variety of selection parameters are supported by
+ &man.auditreduce.1;, including event type, event class,
user, date or time of the event, and the file path or object
acted on.</para>
- <para>For example, the <command>praudit</command> utility will
- dump the entire contents of a specified audit log in plain
- text:</para>
+ <para>For example, &man.praudit.1; will dump the entire
+ contents of a specified audit log in plain text:</para>
<screen>&prompt.root; <userinput>praudit /var/audit/AUDITFILE</userinput></screen>
@@ -569,11 +565,11 @@ www:fc,+ex:no</programlisting>
the audit log to dump.</para>
<para>Audit trails consist of a series of audit records made up
- of tokens, which <command>praudit</command> prints
- sequentially one per line. Each token is of a specific type,
- such as <literal>header</literal> holding an audit record
- header, or <literal>path</literal> holding a file path from a
- name lookup. The following is an example of an
+ of tokens, which &man.praudit.1; prints sequentially one per
+ line. Each token is of a specific type, such as
+ <literal>header</literal> holding an audit record header, or
+ <literal>path</literal> holding a file path from a name
+ lookup. The following is an example of an
<literal>execve</literal> event:</para>
<programlisting>header,133,10,execve(2),0,Mon Sep 25 15:58:03 2006, + 384 msec
@@ -605,9 +601,9 @@ trailer,133</programlisting>
successful execution, and the <literal>trailer</literal>
concludes the record.</para>
- <para><command>praudit</command> also supports
- an XML output format, which can be selected using the
- <option>-x</option> argument.</para>
+ <para><acronym>XML</acronym> output format is also supported by
+ &man.praudit.1;, and can be selected using
+ <option>-x</option>.</para>
</sect2>
<sect2>
@@ -619,20 +615,19 @@ trailer,133</programlisting>
<screen>&prompt.root; <userinput>auditreduce -u trhodes /var/audit/AUDITFILE | praudit</userinput></screen>
- <para>This will select all audit records produced for the user
- <username>trhodes</username> stored in the
- <filename><replaceable>AUDITFILE</replaceable></filename>
- file.</para>
+ <para>This will select all audit records produced for
+ <username>trhodes</username> stored in
+ <filename><replaceable>AUDITFILE</replaceable></filename>.</para>
</sect2>
<sect2>
<title>Delegating Audit Review Rights</title>
<para>Members of the <groupname>audit</groupname> group are
- given permission to read audit trails in
- <filename class="directory">/var/audit</filename>; by default, this group is
- empty, so only the <username>root</username> user may read
- audit trails. Users may be added to the
+ given permission to read audit trails in <filename
+ class="directory">/var/audit</filename>; by default, this
+ group is empty, so only the <username>root</username> user
+ may read audit trails. Users may be added to the
<groupname>audit</groupname> group in order to delegate audit
review rights to the user. As the ability to track audit log
contents provides significant insight into the behavior of
@@ -674,9 +669,9 @@ trailer,133</programlisting>
SSH session, then a continuous stream of audit events will
be generated at a high rate, as each event being printed
will generate another event. It is advisable to run
- <command>praudit</command> on an audit pipe device from
- sessions without fine-grained I/O auditing in order to avoid
- this happening.</para>
+ &man.praudit.1; on an audit pipe device from sessions
+ without fine-grained I/O auditing in order to avoid this
+ happening.</para>
</warning>
</sect2>
@@ -684,24 +679,23 @@ trailer,133</programlisting>
<title>Rotating Audit Trail Files</title>
<para>Audit trails are written to only by the kernel, and
- managed only by the audit daemon,
- <application>auditd</application>. Administrators should not
- attempt to use &man.newsyslog.conf.5; or other tools to
- directly rotate audit logs. Instead, the
- <command>audit</command> management tool may be used to shut
- down auditing, reconfigure the audit system, and perform log
- rotation. The following command causes the audit daemon to
- create a new audit log and signal the kernel to switch to
- using the new log. The old log will be terminated and
- renamed, at which point it may then be manipulated by the
- administrator.</para>
+ managed only by the audit daemon, &man.auditd.8;.
+ Administrators should not attempt to use
+ &man.newsyslog.conf.5; or other tools to directly rotate
+ audit logs. Instead, the &man.audit.8; management tool may
+ be used to shut down auditing, reconfigure the audit system,
+ and perform log rotation. The following command causes the
+ audit daemon to create a new audit log and signal the kernel
+ to switch to using the new log. The old log will be
+ terminated and renamed, at which point it may then be
+ manipulated by the administrator.</para>
<screen>&prompt.root; <userinput>audit -n</userinput></screen>
<warning>
- <para>If the <application>auditd</application> daemon is not
- currently running, this command will fail and an error
- message will be produced.</para>
+ <para>If &man.auditd.8; is not currently running, this
+ command will fail and an error message will be
+ produced.</para>
</warning>
<para>Adding the following line to
@@ -710,11 +704,11 @@ trailer,133</programlisting>
<programlisting>0 */12 * * * root /usr/sbin/audit -n</programlisting>
- <para>The change will take effect once you have saved the
- new <filename>/etc/crontab</filename>.</para>
+ <para>The change will take effect once you have saved the new
+ <filename>/etc/crontab</filename>.</para>
<para>Automatic rotation of the audit trail file based on file
- size is possible via the <option>filesz</option> option in
+ size is possible using <option>filesz</option> in
&man.audit.control.5;, and is described in the configuration
files section of this chapter.</para>
</sect2>
diff --git a/en_US.ISO8859-1/books/handbook/basics/chapter.xml b/en_US.ISO8859-1/books/handbook/basics/chapter.xml
index 3a5544e5ed..d9dd5a98eb 100644
--- a/en_US.ISO8859-1/books/handbook/basics/chapter.xml
+++ b/en_US.ISO8859-1/books/handbook/basics/chapter.xml
@@ -57,7 +57,7 @@
</listitem>
<listitem>
- <para>What a shell is, and how to change your default login
+ <para>What a shell is, and how to change the default login
environment.</para>
</listitem>
@@ -87,10 +87,10 @@
<para>&os; can be used in various ways. One of them is typing
commands to a text terminal. A lot of the flexibility and power
- of a &unix; operating system is readily available at your hands
- when using &os; this way. This section describes what
+ of a &unix; operating system is readily available when using
+ &os; this way. This section describes what
<quote>terminals</quote> and <quote>consoles</quote> are, and
- how you can use them in &os;.</para>
+ how to use them in &os;.</para>
<sect2 id="consoles-intro">
<title>The Console</title>
@@ -144,15 +144,16 @@ login:</screen>
<screen>login:</screen>
- <para>Type the username that was configured during <link
- linkend="bsdinstall-addusers">system installation</link> and
- press <keycap>Enter</keycap>. Then enter the password
- associated with the username and press <keycap>Enter</keycap>.
- The password is <emphasis>not echoed</emphasis> for security
+ <para>Type the username that was configured during system
+ installation, as described in <xref
+ linkend="bsdinstall-addusers"/>, and press
+ <keycap>Enter</keycap>. Then enter the password associated
+ with the username and press <keycap>Enter</keycap>. The
+ password is <emphasis>not echoed</emphasis> for security
reasons.</para>
- <para>Once the correct password is input, the message of
- the day (<acronym>MOTD</acronym>) will be displayed followed
+ <para>Once the correct password is input, the message of the
+ day (<acronym>MOTD</acronym>) will be displayed followed
by a command prompt (a <literal>#</literal>,
<literal>$</literal>, or <literal>%</literal> character). You
are now logged into the &os; console and ready to try the
@@ -165,8 +166,8 @@ login:</screen>
<para>&os; can be configured to provide many virtual consoles
for inputting commands. Each virtual console has its own
login prompt and output channel, and &os; takes care of
- properly redirecting keyboard input and monitor output as you
- switch between virtual consoles.</para>
+ properly redirecting keyboard input and monitor output as
+ switching occurs between virtual consoles.</para>
<para>Special key combinations have been reserved by &os; for
switching consoles.<footnote>
@@ -228,10 +229,10 @@ ttyv8 "/usr/X11R6/bin/xdm -nodaemon" xterm off secure</programlisting>
<title>Single User Mode Console</title>
<para>A detailed description of <quote>single user mode</quote>
- can be found <link linkend="boot-singleuser">here</link>.
- There is only one console when &os; is in single user mode as
- no other virtual consoles are available in this mode. The
- settings for single user mode are found in this section of
+ can be found in <xref linkend="boot-singleuser"/>. There is
+ only one console when &os; is in single user mode as no other
+ virtual consoles are available in this mode. The settings
+ for single user mode are found in this section of
<filename>/etc/ttys</filename>:</para>
<programlisting># name getty type status comments
@@ -249,11 +250,11 @@ console none unknown off secure</programlisting>
without prompting for a password.</para>
<para><emphasis>Be careful when changing this setting to
- <literal>insecure</literal></emphasis>. If you ever
- forget the <username>root</username> password, booting into
- single user mode is still possible, but may be difficult for
- someone who is not comfortable with the &os; booting
- process.</para>
+ <literal>insecure</literal></emphasis>. If the
+ <username>root</username> password is forgotten, booting
+ into single user mode is still possible, but may be
+ difficult for someone who is not comfortable with the &os;
+ booting process.</para>
</note>
</sect2>
@@ -301,6 +302,15 @@ console none unknown off secure</programlisting>
managing requests for hardware devices, peripherals, memory, and
CPU time fairly to each user.</para>
+ <para>Much more information about user accounts is in the chapter
+ about <link linkend="users">accounts</link>. It is important to
+ understand that each person (user) who uses the computer should be
+ given their own username and password. The system keeps track
+ of the people using the computer based on this username. Since
+ it is often the case that several people are working on the same
+ project &unix; also provides groups. Several users can be placed
+ in the same group.</para>
+
<para>Because the system is capable of supporting multiple users,
everything the system manages has a set of permissions governing
who can read, write, and execute the resource. These
@@ -382,7 +392,7 @@ console none unknown off secure</programlisting>
</tgroup>
</informaltable>
<indexterm>
- <primary><command>ls</command></primary>
+ <primary>&man.ls.1;</primary>
</indexterm>
<indexterm><primary>directories</primary></indexterm>
@@ -424,10 +434,10 @@ total 530
write, and execute permissions. The executable bit for a
directory has a slightly different meaning than that of files.
When a directory is marked executable, it means it is possible
- to change into that directory using
- <application>cd</application>. This also means that it is
- possible to access the files within that directory, subject to
- the permissions on the files themselves.</para>
+ to change into that directory using &man.cd.1;. This also
+ means that it is possible to access the files within that
+ directory, subject to the permissions on the files
+ themselves.</para>
<para>In order to perform a directory listing, the read permission
must be set on the directory. In order to delete a file that
@@ -588,10 +598,9 @@ total 530
<para>In addition to file permissions, &os; supports the use of
<quote>file flags</quote>. These flags add an additional
- level of security and control over files, but not
- directories. With file flags, even
- <username>root</username> can be prevented from removing or
- altering files.</para>
+ level of security and control over files, but not directories.
+ With file flags, even <username>root</username> can be
+ prevented from removing or altering files.</para>
<para>File flags are modified using &man.chflags.1;. For
example, to enable the system undeletable flag on the file
@@ -669,7 +678,7 @@ total 530
<para>Note that a <literal>s</literal> is now part of the
permission set designated for the file owner, replacing the
executable bit. This allows utilities which need elevated
- permissions, such as <command>passwd</command>.</para>
+ permissions, such as &man.passwd.1;.</para>
<note>
<para>The <literal>nosuid</literal> &man.mount.8; option will
@@ -680,10 +689,10 @@ total 530
</note>
<para>To view this in real time, open two terminals. On
- one, start the <command>passwd</command> process as a normal
- user. While it waits for a new password, check the process
+ one, type <command>passwd</command> as a normal user.
+ While it waits for a new password, check the process
table and look at the user information for
- <command>passwd</command>:</para>
+ &man.passwd.1;:</para>
<para>In terminal A:</para>
@@ -697,9 +706,9 @@ Old Password:</screen>
<screen>trhodes 5232 0.0 0.2 3420 1608 0 R+ 2:10AM 0:00.00 grep passwd
root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen>
- <para>As stated above, the <command>passwd</command> is run
- by a normal user, but is using the effective
- <acronym>UID</acronym> of <username>root</username>.</para>
+ <para>Although &man.passwd.1; is run as a normal user, it is
+ using the effective <acronym>UID</acronym> of
+ <username>root</username>.</para>
<para>The <literal>setgid</literal> permission performs the
same function as the <literal>setuid</literal> permission;
@@ -709,8 +718,7 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen>
user who started the process.</para>
<para>To set the <literal>setgid</literal> permission on a
- file, provide <command>chmod</command> with a leading two
- (2):</para>
+ file, provide &man.chmod.1; with a leading two (2):</para>
<screen>&prompt.root; <userinput>chmod 2755 sgidexample.sh</userinput></screen>
@@ -855,8 +863,7 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen>
<row>
<entry><filename
class="directory">/etc/namedb/</filename></entry>
- <entry><command>named</command> configuration files.
- Refer to &man.named.8; for details.</entry>
+ <entry>&man.named.8; configuration files.</entry>
</row>
<row>
@@ -870,8 +877,7 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen>
<row>
<entry><filename
class="directory">/etc/ppp/</filename></entry>
- <entry><command>ppp</command> configuration files as
- described in &man.ppp.8;.</entry>
+ <entry>&man.ppp.8; configuration files.</entry>
</row>
<row>
@@ -967,26 +973,26 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen>
<entry><filename
class="directory">/usr/local/</filename></entry>
<entry>Local executables and libraries. Also used as
- the default destination for the &os; ports
- framework. Within
- <filename class="directory">/usr/local</filename>, the
+ the default destination for the &os; ports framework.
+ Within <filename
+ class="directory">/usr/local</filename>, the
general layout sketched out by &man.hier.7; for
<filename class="directory">/usr</filename> should be
used. Exceptions are the man directory, which is
- directly under
- <filename class="directory">/usr/local</filename>
- rather than under
- <filename class="directory">/usr/local/share</filename>,
- and the ports documentation is in
- <filename class="directory">share/doc/<replaceable>port</replaceable></filename>.</entry>
+ directly under <filename
+ class="directory">/usr/local</filename>
+ rather than under <filename
+ class="directory">/usr/local/share</filename>,
+ and the ports documentation is in <filename
+ class="directory">share/doc/<replaceable>port</replaceable></filename>.</entry>
</row>
<row>
<entry><filename
class="directory">/usr/obj/</filename></entry>
<entry>Architecture-specific target tree produced by
- building the
- <filename class="directory">/usr/src</filename>
+ building the <filename
+ class="directory">/usr/src</filename>
tree.</entry>
</row>
@@ -1051,8 +1057,8 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen>
<entry><filename
class="directory">/var/tmp/</filename></entry>
<entry>Temporary files which are usually preserved
- across a system reboot, unless
- <filename class="directory">/var</filename> is a
+ across a system reboot, unless <filename
+ class="directory">/var</filename> is a
memory-based file system.</entry>
</row>
@@ -1078,47 +1084,45 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen>
<para>Files are stored in directories. A directory may contain no
files, or it may contain many hundreds of files. A directory
- can also contain other directories, allowing you to build up a
- hierarchy of directories within one another in order to organize
+ can also contain other directories, allowing a hierarchy of
+ directories within one another in order to organize
data.</para>
<para>Files and directories are referenced by giving the file or
directory name, followed by a forward slash,
<literal>/</literal>, followed by any other directory names that
- are necessary. For example, if the directory
- <filename class="directory">foo</filename> contains a directory
+ are necessary. For example, if the directory <filename
+ class="directory">foo</filename> contains a directory
<filename class="directory">bar</filename> which contains the
file <filename>readme.txt</filename>, the full name, or
<firstterm>path</firstterm>, to the file is
<filename>foo/bar/readme.txt</filename>. Note that this is
- different from &windows; which uses
- <literal>\</literal> to separate file and directory
- names. &os; does not use drive letters, or other drive names in
- the path. For example, you would not type
- <filename>c:/foo/bar/readme.txt</filename> on &os;.</para>
+ different from &windows; which uses <literal>\</literal> to
+ separate file and directory names. &os; does not use drive
+ letters, or other drive names in the path. For example, one
+ would not type <filename>c:/foo/bar/readme.txt</filename> on
+ &os;.</para>
<para>Directories and files are stored in a file system. Each
file system contains exactly one directory at the very top
level, called the <firstterm>root directory</firstterm> for that
- file system. This root directory can contain other
- directories. One file system is designated the
- <firstterm>root file system</firstterm> or <literal>/</literal>.
- Every other file system is <firstterm>mounted</firstterm> under
- the root file system. No matter how many disks you have on your
- &os; system, every directory appears to be part of the same
- disk.</para>
-
- <para>Suppose you have three file systems, called
- <literal>A</literal>, <literal>B</literal>, and
- <literal>C</literal>. Each file system has one root directory,
- which contains two other directories, called
- <literal>A1</literal>, <literal>A2</literal> (and likewise
- <literal>B1</literal>, <literal>B2</literal> and
+ file system. This root directory can contain other directories.
+ One file system is designated the <firstterm>root file
+ system</firstterm> or <literal>/</literal>. Every other file
+ system is <firstterm>mounted</firstterm> under the root file
+ system. No matter how many disks are on the &os; system, every
+ directory appears to be part of the same disk.</para>
+
+ <para>Consider three file systems, called <literal>A</literal>,
+ <literal>B</literal>, and <literal>C</literal>. Each file
+ system has one root directory, which contains two other
+ directories, called <literal>A1</literal>, <literal>A2</literal>
+ (and likewise <literal>B1</literal>, <literal>B2</literal> and
<literal>C1</literal>, <literal>C2</literal>).</para>
- <para>Call <literal>A</literal> the root file system. If you used
- <command>ls</command> to view the contents of this directory you
- would see two subdirectories, <literal>A1</literal> and
+ <para>Call <literal>A</literal> the root file system. If
+ &man.ls.1; is used to view the contents of this directory,
+ it will show two subdirectories, <literal>A1</literal> and
<literal>A2</literal>. The directory tree looks like
this:</para>
@@ -1137,11 +1141,11 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen>
</mediaobject>
<para>A file system must be mounted on to a directory in another
- file system. When mounting file system
- <literal>B</literal> on to the directory <literal>A1</literal>,
- the root directory of <literal>B</literal> replaces
- <literal>A1</literal>, and the directories in
- <literal>B</literal> appear accordingly:</para>
+ file system. When mounting file system <literal>B</literal>
+ on to the directory <literal>A1</literal>, the root directory
+ of <literal>B</literal> replaces <literal>A1</literal>, and
+ the directories in <literal>B</literal> appear
+ accordingly:</para>
<mediaobject>
<imageobject>
@@ -1163,10 +1167,9 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen>
<para>Any files that are in the <literal>B1</literal> or
<literal>B2</literal> directories can be reached with the path
- <filename class="directory">/A1/B1</filename> or
- <filename class="directory">/A1/B2</filename> as
- necessary. Any files that were in
- <filename class="directory">/A1</filename> have
+ <filename class="directory">/A1/B1</filename> or <filename
+ class="directory">/A1/B2</filename> as necessary. Any files
+ that were in <filename class="directory">/A1</filename> have
been temporarily hidden. They will reappear if
<literal>B</literal> is <firstterm>unmounted</firstterm> from
<literal>A</literal>.</para>
@@ -1194,9 +1197,8 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen>
</mediaobject>
<para>and the paths would be
- <filename class="directory">/A2/B1</filename> and
- <filename class="directory">/A2/B2</filename>
- respectively.</para>
+ <filename class="directory">/A2/B1</filename> and <filename
+ class="directory">/A2/B2</filename> respectively.</para>
<para>File systems can be mounted on top of one another.
Continuing the last example, the <literal>C</literal> file
@@ -1252,10 +1254,6 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen>
</textobject>
</mediaobject>
- <para>Typically you create file systems when installing &os;
- and decide where to mount them, and then never change them
- unless you add a new disk.</para>
-
<para>It is entirely possible to have one large root file system,
and not need to create any others. There are some drawbacks to
this approach, and one advantage.</para>
@@ -1268,9 +1266,9 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen>
<firstterm>mount options</firstterm>. For example, the root
file system can be mounted read-only, making it impossible
for users to inadvertently delete or edit a critical file.
- Separating user-writable file systems, such as
- <filename class="directory">/home</filename>, from other
- file systems allows them to be mounted
+ Separating user-writable file systems, such as <filename
+ class="directory">/home</filename>, from other file
+ systems allows them to be mounted
<firstterm>nosuid</firstterm>. This option prevents the
<firstterm>suid</firstterm>/<firstterm>guid</firstterm> bits
on executables stored on the file system from taking effect,
@@ -1287,9 +1285,9 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen>
</listitem>
<listitem>
- <para>&os;'s file systems are very robust should you lose
- power. However, a power loss at a critical point could
- still damage the structure of the file system. By splitting
+ <para>&os;'s file systems are robust if power is lost.
+ However, a power loss at a critical point could still
+ damage the structure of the file system. By splitting
data over multiple file systems it is more likely that the
system will still come up, making it easier to restore from
backup as necessary.</para>
@@ -1365,8 +1363,9 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen>
<entry>Normally the same size as the enclosing slice.
This allows utilities that need to work on the entire
slice, such as a bad block scanner, to work on the
- <literal>c</literal> partition. You would not normally
- create a file system on this partition.</entry>
+ <literal>c</literal> partition. A file system would not
+ normally be
+ created on this partition.</entry>
</row>
<row>
@@ -1393,7 +1392,7 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen>
<literal>s</literal>, starting at 1. So
<quote>da0<emphasis>s1</emphasis></quote> is the first slice on
the first SCSI drive. There can only be four physical slices on
- a disk, but you can have logical slices inside physical slices
+ a disk, but there can be logical slices inside physical slices
of the appropriate type. These extended slices are numbered
starting at 5, so <quote>ad0<emphasis>s5</emphasis></quote> is
the first extended slice on the first IDE disk. These devices
@@ -1404,17 +1403,18 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen>
<firstterm>partitions</firstterm>, which are represented as
letters from <literal>a</literal> to <literal>h</literal>. This
letter is appended to the device name, so
- <quote>da0<emphasis>a</emphasis></quote> is the <literal>a</literal> partition on
- the first <literal>da</literal> drive, which is <quote>dangerously
- dedicated</quote>. <quote>ad1s3<emphasis>e</emphasis></quote> is
- the fifth partition in the third slice of the second IDE disk
- drive.</para>
+ <quote>da0<emphasis>a</emphasis></quote> is the
+ <literal>a</literal> partition on the first
+ <literal>da</literal> drive, which is <quote>dangerously
+ dedicated</quote>. <quote>ad1s3<emphasis>e</emphasis></quote>
+ is the fifth partition in the third slice of the second IDE
+ disk drive.</para>
<para>Finally, each disk on the system is identified. A disk name
starts with a code that indicates the type of disk, and then a
number, indicating which disk it is. Unlike slices, disk
- numbering starts at 0. Common codes that you will see are
- listed in <xref linkend="basics-dev-codes"/>.</para>
+ numbering starts at 0. Common codes are listed in <xref
+ linkend="basics-dev-codes"/>.</para>
<para>When referring to a partition, include the disk name,
<literal>s</literal>, the slice number, and then the partition
@@ -1568,12 +1568,11 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen>
<para>The file system is best visualized as a tree,
rooted, as it were, at <filename class="directory">/</filename>.
- <filename class="directory">/dev</filename>,
- <filename class="directory">/usr</filename>, and the
- other directories in the root directory are branches, which may
- have their own branches, such as
- <filename class="directory">/usr/local</filename>, and so
- on.</para>
+ <filename class="directory">/dev</filename>, <filename
+ class="directory">/usr</filename>, and the other directories
+ in the root directory are branches, which may have their own
+ branches, such as <filename
+ class="directory">/usr/local</filename>, and so on.</para>
<indexterm><primary>root file system</primary></indexterm>
<para>There are various reasons to house some of these
@@ -1583,14 +1582,13 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen>
<filename class="directory">spool/</filename>, and various types
of temporary files, and as such, may get filled up. Filling up
the root file system is not a good idea, so splitting <filename
- class="directory">/var</filename> from
- <filename class="directory">/</filename> is often
- favorable.</para>
+ class="directory">/var</filename> from <filename
+ class="directory">/</filename> is often favorable.</para>
<para>Another common reason to contain certain directory trees on
other file systems is if they are to be housed on separate
- physical disks, or are separate virtual disks, such as
- <link linkend="network-nfs">Network File System</link> mounts,
+ physical disks, or are separate virtual disks, such as Network
+ File System mounts, described in <xref linkend="network-nfs"/>,
or CDROM drives.</para>
<sect2 id="disks-fstab">
@@ -1601,7 +1599,7 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen>
<secondary>mounted with fstab</secondary>
</indexterm>
- <para>During the <link linkend="boot">boot process</link>,
+ <para>During the boot process (<xref linkend="boot"/>),
file systems listed in <filename>/etc/fstab</filename> are
automatically mounted except for the entries containing
<option>noauto</option>. This file contains entries in the
@@ -1641,8 +1639,8 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen>
<term><literal>options</literal></term>
<listitem>
- <para>Either <option>rw</option> for read-write
- file systems, or <option>ro</option> for read-only file
+ <para>Either <option>rw</option> for read-write file
+ systems, or <option>ro</option> for read-only file
systems, followed by any other options that may be
needed. A common option is <option>noauto</option> for
file systems not normally mounted during the boot
@@ -1684,7 +1682,7 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen>
</sect2>
<sect2 id="disks-mount">
- <title>The <command>mount</command> Command</title>
+ <title>Using &man.mount.8;</title>
<indexterm>
<primary>file systems</primary>
@@ -1802,14 +1800,14 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen>
</sect2>
<sect2 id="disks-umount">
- <title>The <command>umount</command> Command</title>
+ <title>Using &man.umount.8;</title>
<indexterm>
<primary>file systems</primary>
<secondary>unmounting</secondary>
</indexterm>
- <para>To unmount a filesystem use &man.umount.8;. This command
+ <para>To unmount a file system use &man.umount.8;. This command
takes one parameter which can be a mountpoint, device name,
<option>-a</option> or <option>-A</option>.</para>
@@ -1836,27 +1834,27 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen>
processes that are run by &os;.</para>
<para>Each process is uniquely identified by a number called a
- <firstterm>process ID</firstterm>
- (<firstterm>PID</firstterm>). Similar to files, each process
- has one owner and group, and the owner and group permissions are
- used to determine which files and devices the process can open.
- Most processes also have a parent process that started them.
- For example, the shell is a process, and any command started in
- the shell is a process which has the shell as its parent
- process. The exception is a special process called
- &man.init.8; which is always the first process to start at boot
- time and which always has a PID of 1.</para>
+ <firstterm>process ID</firstterm> (<acronym>PID</acronym>).
+ Similar to files, each process has one owner and group, and
+ the owner and group permissions are used to determine which
+ files and devices the process can open. Most processes also
+ have a parent process that started them. For example, the
+ shell is a process, and any command started in the shell is a
+ process which has the shell as its parent process. The
+ exception is a special process called &man.init.8; which is
+ always the first process to start at boot time and which always
+ has a <acronym>PID</acronym> of 1.</para>
<para>To see the processes on the system, use &man.ps.1; and
&man.top.1;. To display a static list of the currently running
- processes, their PIDs, how much memory they are using, and the
- command they were started with, use <command>ps</command>. To
- display all the running processes and update the display every
- few seconds so that you can interactively see what the computer
- is doing, use <command>top</command>.</para>
+ processes, their <acronym>PID</acronym>s, how much memory they
+ are using, and the command they were started with, use
+ &man.ps.1;. To display all the running processes and update
+ the display every few seconds in order to interactively see
+ what the computer is doing, use &man.top.1;.</para>
- <para>By default, <command>ps</command> only shows the commands
- that are running and owned by the user. For example:</para>
+ <para>By default, &man.ps.1; only shows the commands that are
+ running and owned by the user. For example:</para>
<screen>&prompt.user; <userinput>ps</userinput>
PID TT STAT TIME COMMAND
@@ -1877,15 +1875,16 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen>
<para>The output from &man.ps.1; is organized into a number of
columns. The <literal>PID</literal> column displays the process
- ID. PIDs are assigned starting at 1, go up to 99999, then wrap
- around back to the beginning. However, a PID is not reassigned
- if it is already in use. The <literal>TT</literal> column shows
- the tty the program is running on and <literal>STAT</literal>
- shows the program's state. <literal>TIME</literal> is the
- amount of time the program has been running on the CPU. This is
- usually not the elapsed time since the program was started, as
- most programs spend a lot of time waiting for things to happen
- before they need to spend time on the CPU. Finally,
+ ID. <acronym>PID</acronym>s are assigned starting at 1, go up
+ to 99999, then wrap around back to the beginning. However, a
+ <acronym>PID</acronym> is not reassigned if it is already in
+ use. The <literal>TT</literal> column shows the tty the program
+ is running on and <literal>STAT</literal> shows the program's
+ state. <literal>TIME</literal> is the amount of time the
+ program has been running on the CPU. This is usually not the
+ elapsed time since the program was started, as most programs
+ spend a lot of time waiting for things to happen before they
+ need to spend time on the CPU. Finally,
<literal>COMMAND</literal> is the command that was used to start
the program.</para>
@@ -1920,25 +1919,25 @@ Swap: 256M Total, 38M Used, 217M Free, 15% Inuse
...</screen>
<para>The output is split into two sections. The header (the
- first five lines) shows the PID of the last process to run, the
- system load averages (which are a measure of how busy the system
- is), the system uptime (time since the last reboot) and the
- current time. The other figures in the header relate to how
- many processes are running (47 in this case), how much memory
- and swap space has been used, and how much time the system is
- spending in different CPU states.</para>
+ first five lines) shows the <acronym>PID</acronym> of the last
+ process to run, the system load averages (which are a measure
+ of how busy the system is), the system uptime (time since the
+ last reboot) and the current time. The other figures in the
+ header relate to how many processes are running (47 in this
+ case), how much memory and swap space has been used, and how
+ much time the system is spending in different CPU states.</para>
<para>Below the header is a series of columns containing similar
- information to the output from &man.ps.1;, such as the PID,
- username, amount of CPU time, and the command that started the
- process. By default, &man.top.1; also displays the amount of
- memory space taken by the process. This is split into two
- columns: one for total size and one for resident size. Total
- size is how much memory the application has needed and the
- resident size is how much it is actually using at the moment.
- In this example, <application>mutt</application> has
- required almost 8&nbsp;MB of RAM, but is currently only using
- 5&nbsp;MB.</para>
+ information to the output from &man.ps.1;, such as the
+ <acronym>PID</acronym>, username, amount of CPU time, and the
+ command that started the process. By default, &man.top.1; also
+ displays the amount of memory space taken by the process.
+ This is split into two columns: one for total size and one for
+ resident size. Total size is how much memory the application
+ has needed and the resident size is how much it is actually
+ using at the moment. In this example,
+ <application>mutt</application> has required almost 8&nbsp;MB
+ of RAM, but is currently only using 5&nbsp;MB.</para>
<para>&man.top.1; automatically updates the display every two
seconds. A different interval can be specified with
@@ -1966,14 +1965,13 @@ Swap: 256M Total, 38M Used, 217M Free, 15% Inuse
<para>There is a convention to name programs that normally run as
daemons with a trailing <quote>d</quote>.
<application>BIND</application> is the Berkeley Internet Name
- Domain, but the actual program that executes is
- <command>named</command>. The <application>Apache</application>
- web server program is <command>httpd</command> and the
- line printer spooling daemon is <command>lpd</command>. This is
- only a naming convention. For example, the main mail daemon for
- the <application>Sendmail</application> application is
- <command>sendmail</command>, and not
- <command>maild</command>.</para>
+ Domain, but the actual program that executes is &man.named.8;.
+ The <application>Apache</application> web server program is
+ <command>httpd</command> and the line printer spooling daemon
+ is &man.lpd.8;. This is only a naming convention. For example,
+ the main mail daemon for the <application>Sendmail</application>
+ application is &man.sendmail.8;, and not
+ <literal>maild</literal>.</para>
<para>One way to communicate with a daemon, or any running
process, is to send a <firstterm>signal</firstterm> using
@@ -2035,15 +2033,15 @@ Swap: 256M Total, 38M Used, 217M Free, 15% Inuse
<title>Sending a Signal to a Process</title>
<para>This example shows how to send a signal to &man.inetd.8;.
- The <command>inetd</command> configuration file is
- <filename>/etc/inetd.conf</filename>, and
- <command>inetd</command> will re-read this configuration file
- when it is sent a <literal>SIGHUP</literal>.</para>
+ The &man.inetd.8; configuration file is
+ <filename>/etc/inetd.conf</filename>, and &man.inetd.8; will
+ re-read this configuration file when it is sent a
+ <literal>SIGHUP</literal>.</para>
<step>
- <para>Find the PID of the process you want to send the signal
- to using &man.pgrep.1;. In this example, the PID for
- &man.inetd.8; is 198:</para>
+ <para>Find the <acronym>PID</acronym> of the process to send
+ the signal to using &man.pgrep.1;. In this example, the
+ <acronym>PID</acronym> for &man.inetd.8; is 198:</para>
<screen>&prompt.user; <userinput>pgrep -l inetd</userinput>
198 inetd -wW</screen>
@@ -2060,12 +2058,13 @@ Swap: 256M Total, 38M Used, 217M Free, 15% Inuse
&prompt.root; <userinput>/bin/kill -s HUP 198</userinput></screen>
<para>Like most &unix; commands, &man.kill.1; will not print
- any output if it is successful. If you send a signal to a
- process that you do not own, you will instead see
+ any output if it is successful. If a signal is sent to a
+ process not owned by that user, the message
<errorname>kill: <replaceable>PID</replaceable>: Operation
- not permitted</errorname>. Mistyping the PID will either
- send the signal to the wrong process, which could have
- negative results, or will send the signal to a PID that is
+ not permitted</errorname> will be displayed. Mistyping
+ the <acronym>PID</acronym> will either send the signal to
+ the wrong process, which could have negative results, or
+ will send the signal to a <acronym>PID</acronym> that is
not currently in use, resulting in the error
<errorname>kill: <replaceable>PID</replaceable>: No such
process</errorname>.</para>
@@ -2092,9 +2091,9 @@ Swap: 256M Total, 38M Used, 217M Free, 15% Inuse
<important>
<para>Killing a random process on the system can be a bad idea.
- In particular, &man.init.8;, PID 1, is special. Running
- <command>/bin/kill -s KILL 1</command> is a quick, and
- unrecommended, way to shutdown the system.
+ In particular, &man.init.8;, <acronym>PID</acronym> 1, is
+ special. Running <command>/bin/kill -s KILL 1</command> is
+ a quick, and unrecommended, way to shutdown the system.
<emphasis>Always</emphasis> double check the arguments to
&man.kill.1; <emphasis>before</emphasis> pressing
<keycap>Return</keycap>.</para>
@@ -2112,14 +2111,14 @@ Swap: 256M Total, 38M Used, 217M Free, 15% Inuse
them. Many shells provide built in functions to help with
everyday tasks such as file management, file globbing, command
line editing, command macros, and environment variables. &os;
- comes with several shells, including <command>sh</command>, the
- Bourne Shell, and <command>tcsh</command>, the improved C-shell.
- Other shells are available from the &os; Ports Collection, such
- as <command>zsh</command> and <command>bash</command>.</para>
+ comes with several shells, including the Bourne shell
+ (&man.sh.1;) and the extended C shell (&man.tcsh.1;). Other
+ shells are available from the &os; Ports Collection, such as
+ <command>zsh</command> and <command>bash</command>.</para>
<para>The shell that is used is really a matter of taste. A C
programmer might feel more comfortable with a C-like shell such
- as <command>tcsh</command>. A Linux user might prefer
+ as &man.tcsh.1;. A &linux; user might prefer
<command>bash</command>. Each shell has unique properties that
may or may not work with a user's preferred working environment,
which is why there is a choice of which shell to use.</para>
@@ -2176,7 +2175,8 @@ Swap: 256M Total, 38M Used, 217M Free, 15% Inuse
<row>
<entry><envar>DISPLAY</envar></entry>
- <entry>Network name of the <application>Xorg</application>
+ <entry>Network name of the
+ <application>&xorg;</application>
display to connect to, if available.</entry>
</row>
@@ -2231,13 +2231,13 @@ Swap: 256M Total, 38M Used, 217M Free, 15% Inuse
<indexterm><primary>Bourne shells</primary></indexterm>
<para>How to set an environment variable differs between shells.
- In <command>tcsh</command> and <command>csh</command>, use
+ In &man.tcsh.1; and &man.csh.1;, use
<command>setenv</command> to set environment variables. In
- <command>sh</command> and <command>bash</command>, use
+ &man.sh.1; and <command>bash</command>, use
<command>export</command> to set the current environment
variables. This example sets the default <envar>EDITOR</envar>
to <filename>/usr/local/bin/emacs</filename> for the
- <command>tcsh</command> shell:</para>
+ &man.tcsh.1; shell:</para>
<screen>&prompt.user; <userinput>setenv EDITOR /usr/local/bin/emacs</userinput></screen>
@@ -2254,13 +2254,12 @@ Swap: 256M Total, 38M Used, 217M Free, 15% Inuse
<para>Shells treat special characters, known as meta-characters,
as special representations of data. The most common
- meta-character is <literal>*</literal>, which
- represents any number of characters in a filename.
- Meta-characters can be used to perform filename globbing. For
- example, <command>echo *</command> is equivalent to
- <command>ls</command> because the shell takes all the files that
- match <literal>*</literal> and <command>echo</command> lists
- them on the command line.</para>
+ meta-character is <literal>*</literal>, which represents any
+ number of characters in a filename. Meta-characters can be
+ used to perform filename globbing. For example, <command>echo
+ *</command> is equivalent to &man.ls.1; because the shell
+ takes all the files that match <literal>*</literal> and
+ &man.echo.1; lists them on the command line.</para>
<para>To prevent the shell from interpreting a special character,
escape it from the shell by starting it with a backslash
@@ -2276,9 +2275,8 @@ Swap: 256M Total, 38M Used, 217M Free, 15% Inuse
to use <command>chsh</command>. Running this command will
open the editor that is configured in the
<envar>EDITOR</envar> environment variable, which by default
- is set to <command>vi</command>. Change
- the <quote>Shell:</quote> line to the full path of the
- new shell.</para>
+ is set to &man.vi.1;. Change the <quote>Shell:</quote> line
+ to the full path of the new shell.</para>
<para>Alternately, use <command>chsh -s</command> which will set
the specified shell without opening an editor. For example,
@@ -2289,15 +2287,15 @@ Swap: 256M Total, 38M Used, 217M Free, 15% Inuse
<note>
<para>The new shell <emphasis>must</emphasis> be present in
<filename>/etc/shells</filename>. If the shell was
- installed from the &os; <link linkend="ports">Ports
- Collection</link>, it should be automatically added to
- this file. If it is missing, add it using this
+ installed from the &os; Ports Collection as described in
+ <xref linkend="ports"/>, it should be automatically added
+ to this file. If it is missing, add it using this
command, replacing the path with the path of the
shell:</para>
<screen>&prompt.root; <userinput>echo <replaceable>/usr/local/bin/bash</replaceable> &gt;&gt; /etc/shells</userinput></screen>
- <para>Then rerun <command>chsh</command>.</para>
+ <para>Then rerun &man.chsh.1;.</para>
</note>
</sect2>
</sect1>
@@ -2318,12 +2316,12 @@ Swap: 256M Total, 38M Used, 217M Free, 15% Inuse
</indexterm>
<indexterm>
<primary>editors</primary>
- <secondary><command>ee</command></secondary>
+ <secondary>&man.ee.1;</secondary>
</indexterm>
- <para>A simple editor to learn is <application>ee</application>,
- which stands for easy editor. To start this editor, type
- <command>ee <replaceable>filename</replaceable></command> where
+ <para>A simple editor to learn is &man.ee.1;, which stands for
+ easy editor. To start this editor, type <command>ee
+ <replaceable>filename</replaceable></command> where
<replaceable>filename</replaceable> is the name of the file to
be edited. Once inside the editor, all of the commands for
manipulating the editor's functions are listed at the top of the
@@ -2331,18 +2329,17 @@ Swap: 256M Total, 38M Used, 217M Free, 15% Inuse
<keycap>Ctrl</keycap>, so <literal>^e</literal> expands to
<keycombo
action="simul"><keycap>Ctrl</keycap><keycap>e</keycap></keycombo>.
- To leave <application>ee</application>, press
- <keycap>Esc</keycap>, then choose the <quote>leave
- editor</quote> option from the main menu. The editor will
- prompt you to save any changes if the file has been
+ To leave &man.ee.1;, press <keycap>Esc</keycap>, then choose
+ the <quote>leave editor</quote> option from the main menu.
+ The editor will prompt to save any changes if the file has been
modified.</para>
<indexterm>
- <primary><command>vi</command></primary>
+ <primary>&man.vi.1;</primary>
</indexterm>
<indexterm>
<primary>editors</primary>
- <secondary><command>vi</command></secondary>
+ <secondary>&man.vi.1;</secondary>
</indexterm>
<indexterm>
<primary><command>emacs</command></primary>
@@ -2352,10 +2349,9 @@ Swap: 256M Total, 38M Used, 217M Free, 15% Inuse
<secondary><command>emacs</command></secondary>
</indexterm>
- <para>&os; also comes with more powerful text editors such as
- <application>vi</application> as part of the base system.
- Other editors, like <filename
- role="package">editors/emacs</filename> and
+ <para>&os; also comes with more powerful text editors, such as
+ &man.vi.1;, as part of the base system. Other editors, like
+ <filename role="package">editors/emacs</filename> and
<filename role="package">editors/vim</filename>, are part of the
&os; Ports Collection. These editors offer more functionality
at the expense of being a more complicated to learn. Learning a
@@ -2366,8 +2362,7 @@ Swap: 256M Total, 38M Used, 217M Free, 15% Inuse
<para>Many applications which modify files or require typed input
will automatically open a text editor. To alter the default
editor used, set the <envar>EDITOR</envar> environment
- variable as described in the <link
- linkend="shells">shells</link> section.</para>
+ variable as described in <xref linkend="shells"/>.</para>
</sect1>
<sect1 id="basics-devices">
@@ -2393,8 +2388,23 @@ Swap: 256M Total, 38M Used, 217M Free, 15% Inuse
<sect1 id="binary-formats">
<title>Binary Formats</title>
- <para>To understand why &os; uses the &man.elf.5; format,the three
- currently <quote>dominant</quote> executable formats for &unix;
+ <para>Typically when a command is passed to the shell, the shell
+ will arrange for an executable file to be loaded into memory and
+ a new process is created. Executable files can either be a binary
+ file (usually created by the linker as part of compiling a program)
+ or a shell script (text file to be interpreted by a binary file,
+ like &man.sh.1; or &man.perl.1;). The &man.file.1; command can
+ usually determine what is inside a file.</para>
+
+ <para>Binary files need to have a well defined format for the system
+ to be able to use them properly. Part of the file will be the
+ executable machine code (the instructions that tell the CPU what
+ to do), part of it will be data space with pre-defined values,
+ part will be data space with no pre-defined values, etc. Through
+ time, different binary file formats have evolved.</para>
+
+ <para>To understand why &os; uses the &man.elf.5; format, the three
+ currently <quote>dominant</quote>, executable formats for &unix;
must be described:</para>
<itemizedlist>
@@ -2441,8 +2451,8 @@ Swap: 256M Total, 38M Used, 217M Free, 15% Inuse
the &man.a.out.5; format, a technology tried and proven through
many generations of BSD releases, until the beginning of the 3.X
branch. Though it was possible to build and run native
- <acronym>ELF</acronym> binaries and kernels on a &os;
- system for some time before that, &os; initially resisted the
+ <acronym>ELF</acronym> binaries and kernels on a &os; system
+ for some time before that, &os; initially resisted the
<quote>push</quote> to switch to <acronym>ELF</acronym> as the
default format. Why? When Linux made its painful transition to
<acronym>ELF</acronym>, it was due to their inflexible
@@ -2502,9 +2512,8 @@ Swap: 256M Total, 38M Used, 217M Free, 15% Inuse
programs rewrote them and added simpler support for building
cross compilers and plugging in different formats. Those who
wanted to build cross compilers targeting &os; were out of luck
- since the older sources that &os; had for
- <application>as</application> and <application>ld</application>
- were not up to the task. The new GNU tools chain
+ since the older sources that &os; had for &man.as.1; and
+ &man.ld.1; were not up to the task. The new GNU tools chain
(<application>binutils</application>) supports cross
compiling, <acronym>ELF</acronym>, shared libraries, and C++
extensions. In addition, many vendors release
@@ -2539,8 +2548,8 @@ Swap: 256M Total, 38M Used, 217M Free, 15% Inuse
<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>
<para>where <replaceable>command</replaceable> is the name of
- the command you wish to learn about. For example, to learn
- more about <command>ls</command>, type:</para>
+ the command to learn about. For example, to learn more about
+ &man.ls.1;, type:</para>
<screen>&prompt.user; <userinput>man ls</userinput></screen>
@@ -2587,21 +2596,19 @@ Swap: 256M Total, 38M Used, 217M Free, 15% Inuse
<para>In some cases, the same topic may appear in more than one
section of the online manual. For example, there is a
- <command>chmod</command> user command and a
- <function>chmod()</function> system call. To tell
- <command>man</command> which section to display, specify the
- section number:</para>
+ &man.chmod.1; user command and a
+ <function>chmod()</function> system call. To tell &man.man.1;
+ which section to display, specify the section number:</para>
<screen>&prompt.user; <userinput>man 1 chmod</userinput></screen>
<para>This will display the manual page for the user command
- <command>chmod</command>. References to a particular section
- of the online manual are traditionally placed in parenthesis
- in written documentation, so &man.chmod.1; refers to the
- <command>chmod</command> user command and &man.chmod.2; refers
- to the system call.</para>
+ &man.chmod.1;. References to a particular section of the
+ online manual are traditionally placed in parenthesis in
+ written documentation, so &man.chmod.1; refers to the user
+ command and &man.chmod.2; refers to the system call.</para>
- <para>If you do not know the command name, use <command>man
+ <para>If the command name is unknown, use <command>man
-k</command> to search for keywords in the command
descriptions:</para>
@@ -2611,8 +2618,8 @@ Swap: 256M Total, 38M Used, 217M Free, 15% Inuse
keyword <quote>mail</quote> in their descriptions. This is
equivalent to using &man.apropos.1;.</para>
- <para>To determine what the commands in
- <filename class="directory">/usr/bin</filename> do,
+ <para>To determine what the commands in <filename
+ class="directory">/usr/bin</filename> do,
type:</para>
<screen>&prompt.user; <userinput>cd /usr/bin</userinput>
@@ -2636,7 +2643,7 @@ Swap: 256M Total, 38M Used, 217M Free, 15% Inuse
by the Free Software Foundation (FSF). In addition to manual
pages, these programs may include hypertext documents called
<literal>info</literal> files. These can be viewed using
- <command>info</command> or, if <filename
+ &man.info.1; or, if <filename
role="package">editors/emacs</filename> is installed, the
info mode of <application>emacs</application>.</para>
diff --git a/en_US.ISO8859-1/books/handbook/boot/chapter.xml b/en_US.ISO8859-1/books/handbook/boot/chapter.xml
index 2f4f619f34..c13bec3bbb 100644
--- a/en_US.ISO8859-1/books/handbook/boot/chapter.xml
+++ b/en_US.ISO8859-1/books/handbook/boot/chapter.xml
@@ -16,9 +16,9 @@
<para>The process of starting a computer and loading the operating
system is referred to as <quote>the bootstrap process</quote>,
- or simply <quote>booting</quote>. &os;'s boot process
- provides a great deal of flexibility in customizing what happens
- when the system starts, including the ability to select from
+ or simply <quote>booting</quote>. &os;'s boot process provides
+ a great deal of flexibility in customizing what happens when
+ the system starts, including the ability to select from
different operating systems installed on the same computer,
different versions of the same operating system, or a different
installed kernel.</para>
@@ -73,47 +73,54 @@
to the mechanism used to load the operating system, which has
become shortened to <quote>booting</quote>.</para>
- <indexterm><primary>BIOS</primary></indexterm>
+ <indexterm><primary><acronym>BIOS</acronym></primary></indexterm>
<indexterm>
<primary>Basic Input/Output System</primary>
- <see>BIOS</see>
+ <see><acronym>BIOS</acronym></see>
</indexterm>
- <para>On x86 hardware the Basic Input/Output System (BIOS) is
- responsible for loading the operating system. To do this, the
- BIOS looks on the hard disk for the Master Boot Record (MBR),
- which must be located on a specific place on the disk. The BIOS
- has enough knowledge to load and run the MBR, and assumes that
- the MBR can then carry out the rest of the tasks involved in
- loading the operating system, possibly with the help of the
- BIOS.</para>
+ <para>On x86 hardware the Basic Input/Output System
+ (<acronym>BIOS</acronym>) is responsible for loading the
+ operating system. To do this, the <acronym>BIOS</acronym>
+ looks on the hard disk for the Master Boot Record
+ (<acronym>MBR</acronym>), which must be located in a specific
+ place on the disk. The <acronym>BIOS</acronym> has enough
+ knowledge to load and run the <acronym>MBR</acronym>, and
+ assumes that the <acronym>MBR</acronym> can then carry out the
+ rest of the tasks involved in loading the operating system,
+ possibly with the help of the <acronym>BIOS</acronym>.</para>
- <indexterm><primary>Master Boot Record (MBR)</primary></indexterm>
+ <indexterm><primary>Master Boot Record
+ <acronym>MBR</acronym>)</primary></indexterm>
<indexterm><primary>Boot Manager</primary></indexterm>
<indexterm><primary>Boot Loader</primary></indexterm>
- <para>The code within the MBR is usually referred to as a
- <emphasis>boot manager</emphasis>, especially when it interacts
- with the user. In this case the boot manager usually has more
- code in the first <emphasis>track</emphasis> of the disk or
- within some OS's file system. (A boot manager is sometimes also
- called a <emphasis>boot loader</emphasis>, but &os; uses that
- term for a later stage of booting.) Popular boot managers
- include <application>boot0</application> (aka
+ <para>The code within the <acronym>MBR</acronym> is usually
+ referred to as a <emphasis>boot manager</emphasis>, especially
+ when it interacts with the user. In this case, the boot
+ manager usually has more code in the first
+ <emphasis>track</emphasis> of the disk or within the file
+ system of some operating systems. A boot manager is sometimes
+ also called a <emphasis>boot loader</emphasis>, but &os; uses
+ that term for a later stage of booting. Popular boot managers
+ include <application>boot0</application>, also called
<application>Boot Easy</application>, the standard &os; boot
- manager), <application>Grub</application>,
+ manager, <application>Grub</application>,
<application>GAG</application>, and
- <application>LILO</application>. (Only
- <application>boot0</application> fits within the MBR.)</para>
+ <application>LILO</application>. Only
+ <application>boot0</application> fits within the
+ <acronym>MBR</acronym>.</para>
- <para>If only one operating system is installed, a standard PC MBR
- will suffice. This MBR searches for the first bootable (active)
+ <para>If only one operating system is installed, a standard PC
+ <acronym>MBR</acronym> will suffice. This
+ <acronym>MBR</acronym> searches for the first bootable (active)
slice on the disk, and then runs the code on that slice to load
- the remainder of the operating system. By default, the MBR
- installed by &man.fdisk.8; is such an MBR and is based on
+ the remainder of the operating system. By default, the
+ <acronym>MBR</acronym> installed by &man.fdisk.8; is such an
+ <acronym>MBR</acronym> and is based on
<filename>/boot/mbr</filename>.</para>
<para>If multiple operating systems are present, a different boot
@@ -122,18 +129,18 @@
boot managers are discussed in the next subsection.</para>
<para>The remainder of the &os; bootstrap system is divided
- into three stages. The first stage is run by the MBR, which
- knows just enough to get the computer into a specific state and
- run the second stage. The second stage can do a little bit
- more, before running the third stage. The third stage finishes
- the task of loading the operating system. The work is split
- into three stages because PC standards put limits on the size of
- the programs that can be run at stages one and two. Chaining
- the tasks together allows &os; to provide a more flexible
- loader.</para>
+ into three stages. The first stage is run by the
+ <acronym>MBR</acronym>, which knows just enough to get the
+ computer into a specific state and run the second stage. The
+ second stage can do a little bit more, before running the
+ third stage. The third stage finishes the task of loading the
+ operating system. The work is split into three stages because
+ PC standards put limits on the size of the programs that can
+ be run at stages one and two. Chaining the tasks together
+ allows &os; to provide a more flexible loader.</para>
<indexterm><primary>kernel</primary></indexterm>
- <indexterm><primary><command>init</command></primary></indexterm>
+ <indexterm><primary>&man.init.8;</primary></indexterm>
<para>The kernel is then started and it begins to probe for
devices and initialize them for use. Once the kernel boot
@@ -154,11 +161,11 @@
<title>The Boot Manager</title>
<indexterm><primary>Master Boot Record
- (MBR)</primary></indexterm>
+ (<acronym>MBR</acronym>)</primary></indexterm>
- <para>The code in the MBR or boot manager is sometimes referred
- to as <emphasis>stage zero</emphasis> of the boot process.
- This section discusses two boot managers:
+ <para>The code in the <acronym>MBR</acronym> or boot manager is
+ sometimes referred to as <emphasis>stage zero</emphasis> of
+ the boot process. This section discusses two boot managers:
<application>boot0</application> and
<application>LILO</application>.</para>
@@ -166,12 +173,12 @@
<title>The <application>boot0</application> Boot
Manager:</title>
- <para>The MBR installed by &os;'s installer or
- &man.boot0cfg.8; is based on
+ <para>The <acronym>MBR</acronym> installed by &os;'s installer
+ or &man.boot0cfg.8; is based on
<filename>/boot/boot0</filename>. The size and capability
of <application>boot0</application> is restricted to 446
bytes due to the slice table and <literal>0x55AA</literal>
- identifier at the end of the MBR. If
+ identifier at the end of the <acronym>MBR</acronym>. If
<application>boot0</application> and multiple operating
systems are installed, a message similar to this example
will be displayed at boot time:</para>
@@ -187,18 +194,22 @@ Default: F2</screen>
</example>
<para>Other operating systems, in particular &windows;, will
- overwrite an existing MBR if they are installed after &os;.
- If this happens, or you want to replace the existing MBR
- with the &os; MBR, use the following command:</para>
+ overwrite an existing <acronym>MBR</acronym> if they are
+ installed after &os;. If this happens, or to replace the
+ existing <acronym>MBR</acronym> with the &os;
+ <acronym>MBR</acronym>, use the following command:</para>
<screen>&prompt.root; <userinput>fdisk -B -b /boot/boot0 <replaceable>device</replaceable></userinput></screen>
<para>where <replaceable>device</replaceable> is the boot disk,
- such as <devicename>ad0</devicename> for the first IDE disk,
- <devicename>ad2</devicename> for the first IDE disk on a
- second IDE controller, or <devicename>da0</devicename>
- for the first SCSI disk. To create a custom configuration of
- the MBR, refer to &man.boot0cfg.8;.</para>
+ such as <devicename>ad0</devicename> for the first
+ <acronym>IDE</acronym> disk, <devicename>ad2</devicename>
+ for the first <acronym>IDE</acronym> disk on a second
+ <acronym>IDE</acronym> controller, or
+ <devicename>da0</devicename>
+ for the first <acronym>SCSI</acronym> disk. To create a
+ custom configuration of the <acronym>MBR</acronym>, refer to
+ &man.boot0cfg.8;.</para>
<formalpara>
<title>The LILO Boot Manager:</title>
@@ -235,11 +246,11 @@ label=FreeBSD</programlisting>
constraints, they have been split into two, but are always
installed together. They are copied from the combined
<filename>/boot/boot</filename> by the installer or
- <application>bsdlabel</application>.</para>
+ &man.bsdlabel.8;.</para>
<para>They are located outside file systems, in the first track
of the boot slice, starting with the first sector. This is
- where <link linkend="boot-boot0">boot0</link>, or any other
+ where boot0 (<xref linkend="boot-boot0"/>), or any other
boot manager, expects to find a program to run which will
continue the boot process. The number of sectors used is
easily determined from the size of
@@ -256,9 +267,9 @@ label=FreeBSD</programlisting>
can provide a simple interface to choose the kernel or loader
to run.</para>
- <para><link linkend="boot-loader">loader</link> is much more
- sophisticated and provides a boot configuration which is run
- by <filename>boot2</filename>.</para>
+ <para>However, &man.loader.8; is much more sophisticated and
+ provides a boot configuration which is run by
+ <filename>boot2</filename>.</para>
<example id="boot-boot2-example">
<title><filename>boot2</filename> Screenshot</title>
@@ -276,7 +287,8 @@ boot:</screen>
<para>where <replaceable>diskslice</replaceable> is the disk and
slice to boot from, such as <devicename>ad0s1</devicename>
- for the first slice on the first IDE disk.</para>
+ for the first slice on the first <acronym>IDE</acronym>
+ disk.</para>
<warning>
<title>Dangerously Dedicated Mode</title>
@@ -557,10 +569,10 @@ boot:</screen>
first is the default legacy virtual console command line
environment. After the system finishes booting, a console
login prompt is presented. The second environment is the
- graphical environment provided by
- <link linkend="x11">Xorg</link>. Refer to that chapter for
- more information on how to install and configure a graphical
- display manager and a graphical login manager.</para>
+ graphical environment as described in <xref linkend="x11"/>.
+ Refer to that chapter for more information on how to install
+ and configure a graphical display manager and a graphical
+ login manager.</para>
<sect4 id="boot-splash-function">
<title>Splash Screen Function</title>
@@ -574,8 +586,8 @@ boot:</screen>
<para>To use larger images, up to the maximum resolution of
1024 by 768 pixels, load the <acronym>VESA</acronym>
- module during system boot. For a <ulink
- url="kernelconfig">custom kernel</ulink>, include the
+ module during system boot. For a custom kernel, as
+ described in <xref linkend="kernelconfig"/>, include the
<literal>VESA</literal> kernel configuration option.
Loading <acronym>VESA</acronym> support provides the
ability to display a splash screen image that fills the
@@ -666,8 +678,8 @@ bitmap_name="<replaceable>/boot/splash.bin</replaceable>"</programlisting>
or
<filename><replaceable>bluewave</replaceable>.pcx</filename>.</para>
- <para>Other interesting
- <filename>loader.conf</filename> options include:</para>
+ <para>Other interesting <filename>loader.conf</filename>
+ options include:</para>
<variablelist>
<varlistentry>
@@ -710,10 +722,10 @@ bitmap_name="<replaceable>/boot/splash.bin</replaceable>"</programlisting>
<secondary>boot interaction</secondary>
</indexterm>
- <para>Once the kernel is loaded by either the default <link
- linkend="boot-loader">loader</link> or by <link
- linkend="boot-boot1">boot2</link> which bypasses the loader,
- it examines its boot flags, if any, and adjusts its behavior as
+ <para>Once the kernel is loaded by either the default loader
+ (<xref linkend="boot-loader"/>) or by boot2 (<xref
+ linkend="boot-boot1"/>), which bypasses the loader, it
+ examines any boot flags and adjusts its behavior as
necessary.</para>
<sect2 id="boot-kernel-bootflags">
@@ -807,8 +819,9 @@ bitmap_name="<replaceable>/boot/splash.bin</replaceable>"</programlisting>
<quote>device hints</quote>. These <quote>device hints</quote>
are used by device drivers for device configuration.</para>
- <para>Device hints may also be specified at the <link
- linkend="boot-loader"> Stage 3 boot loader</link> prompt.
+ <para>Device hints may also be specified at the Stage 3 boot
+ loader prompt, as demonstrated in <xref
+ linkend="boot-loader"/>.
Variables can be added using <command>set</command>, removed
with <command>unset</command>, and viewed
<command>show</command>. Variables set in
@@ -882,7 +895,7 @@ bitmap_name="<replaceable>/boot/splash.bin</replaceable>"</programlisting>
<title>Init: Process Control Initialization</title>
<indexterm>
- <primary><command>init</command></primary>
+ <primary>&man.init.8;</primary>
</indexterm>
<para>Once the kernel has finished booting, it passes control to
@@ -897,10 +910,9 @@ bitmap_name="<replaceable>/boot/splash.bin</replaceable>"</programlisting>
<para>The automatic reboot sequence makes sure that the file
systems available on the system are consistent. If they are
not, and &man.fsck.8; cannot fix the inconsistencies of a UFS
- file system, &man.init.8; drops the system into
- <link linkend="boot-singleuser">single-user mode</link> so
- that the system administrator can resolve the problem
- directly.</para>
+ file system, &man.init.8; drops the system into single-user
+ mode (<xref linkend="boot-singleuser"/>) so that the system
+ administrator can resolve the problem directly.</para>
</sect2>
<sect2 id="boot-singleuser">
@@ -909,14 +921,13 @@ bitmap_name="<replaceable>/boot/splash.bin</replaceable>"</programlisting>
<indexterm><primary>single-user mode</primary></indexterm>
<indexterm><primary>console</primary></indexterm>
- <para>This mode can be reached through the <link
- linkend="boot-autoreboot">automatic reboot sequence</link>,
- the user booting with <option>-s</option>, or by setting
- the <envar>boot_single</envar> variable in
- <command>loader</command>.</para>
+ <para>This mode can be reached through the automatic reboot
+ sequence (<xref linkend="boot-autoreboot"/>), the user booting
+ with <option>-s</option>, or by setting the <envar>boot_
+ single</envar> variable in &man.loader.8;.</para>
<para>It can also be reached by calling &man.shutdown.8; from
- <link linkend="boot-multiuser">multi-user mode</link> without
+ multi-user mode (<xref linkend="boot-multiuser"/>) without
including <option>-r</option> or <option>-h</option>.</para>
<para>If the system <literal>console</literal> is set to
@@ -952,13 +963,13 @@ console none unknown off insecure</programlisting>
<indexterm><primary>multi-user mode</primary></indexterm>
<para>If &man.init.8; finds the file systems to be in order, or
- once the user has finished their commands in <link
- linkend="boot-singleuser">single-user mode</link>, the
- system enters multi-user mode, in which it starts the
- resource configuration of the system.</para>
+ once the user has finished their commands in single-user
+ mode (<xref linkend="boot-singleuser"/>), the system enters
+ multi-user mode, in which it starts the resource configuration
+ of the system.</para>
<sect3 id="boot-rc">
- <title>Resource Configuration (rc)</title>
+ <title>Resource Configuration</title>
<indexterm><primary>rc files</primary></indexterm>
@@ -983,7 +994,7 @@ console none unknown off insecure</programlisting>
<title>Shutdown Sequence</title>
<indexterm>
- <primary><command>shutdown</command></primary>
+ <primary>&man.shutdown.8;</primary>
</indexterm>
<para>Upon controlled shutdown using &man.shutdown.8;,
@@ -997,8 +1008,8 @@ console none unknown off insecure</programlisting>
that support power management, use <command>shutdown -p
now</command> to turn the power off immediately. To reboot a
&os; system, use <command>shutdown -r now</command>. One must
- be <username>root</username> or a member of the
- <groupname>operator</groupname> group in order to run
+ be <username>root</username> or a member of
+ <groupname>operator</groupname> in order to run
&man.shutdown.8;. One can also use &man.halt.8; and
&man.reboot.8;. Refer to their manual pages and to
&man.shutdown.8; for more information.</para>
diff --git a/en_US.ISO8859-1/books/handbook/config/chapter.xml b/en_US.ISO8859-1/books/handbook/config/chapter.xml
index fba2a7c58b..1653f20602 100644
--- a/en_US.ISO8859-1/books/handbook/config/chapter.xml
+++ b/en_US.ISO8859-1/books/handbook/config/chapter.xml
@@ -68,13 +68,12 @@
</listitem>
<listitem>
- <para>How to use the various configuration files in
- <filename class="directory">/etc</filename>.</para>
+ <para>How to use the various configuration files in <filename
+ class="directory">/etc</filename>.</para>
</listitem>
<listitem>
- <para>How to tune &os; using <command>sysctl</command>
- variables.</para>
+ <para>How to tune &os; using &man.sysctl.8; variables.</para>
</listitem>
<listitem>
@@ -120,38 +119,38 @@
<para>When laying out file systems with &man.bsdlabel.8; or
&man.sysinstall.8;, remember that hard drives transfer data
- faster from the outer tracks to the inner. Thus smaller and
- heavier-accessed file systems should be closer to the
+ faster from the outer tracks to the inner. Thus, smaller
+ and heavier-accessed file systems should be closer to the
outside of the drive, while larger partitions like
<filename class="directory">/usr</filename> should be placed
toward the inner parts of the disk. It is a good idea to
- create partitions in an order similar to: root, swap,
- <filename class="directory">/var</filename>,
+ create partitions in an order similar to: <filename
+ class="directory">/</filename>, swap,
+ <filename class="directory">/var</filename>, and
<filename class="directory">/usr</filename>.</para>
<para>The size of the
<filename class="directory">/var</filename> partition
reflects the intended machine's usage. This partition
- <filename class="directory">/var</filename> is used to hold
- mailboxes, log files, and printer spools. Mailboxes and log
- files can grow to unexpected sizes depending on how many
- users exist and how long log files are kept. Most users
- rarely need more than about a gigabyte of free disk space in
- <filename class="directory">/var</filename>.</para>
+ is used to hold mailboxes, log files, and printer spools.
+ Mailboxes and log files can grow to unexpected sizes
+ depending on the number of users and how long log files
+ are kept. On average, most users rarely need more than
+ about a gigabyte of free disk space in <filename
+ class="directory">/var</filename>.</para>
<note>
- <para>There are a few times that a lot of disk space is
- required in
- <filename class="directory">/var/tmp</filename>. When new
- software is installed with &man.pkg.add.1; the packaging
- tools extract a temporary copy of the packages under
- <filename class="directory">/var/tmp</filename>. Large
- software packages, like
+ <para>Sometimes, a lot of disk space is required in
+ <filename class="directory">/var/tmp</filename>. When
+ new software is installed with &man.pkg.add.1;, the
+ packaging tools extract a temporary copy of the packages
+ under <filename class="directory">/var/tmp</filename>.
+ Large software packages, like
<application>Firefox</application>,
<application>OpenOffice</application> or
<application>LibreOffice</application> may be tricky to
- install if there is not enough disk space under
- <filename class="directory">/var/tmp</filename>.</para>
+ install if there is not enough disk space under <filename
+ class="directory">/var/tmp</filename>.</para>
</note>
<para>The <filename class="directory">/usr</filename>
@@ -161,16 +160,14 @@
partition.</para>
<para>When selecting partition sizes, keep the space
- requirements in mind. Running out of space in
- one partition while barely using another can be a
- hassle.</para>
+ requirements in mind. Running out of space in one partition
+ while barely using another can be a hassle.</para>
<note>
- <para>Some users have found that &man.sysinstall.8;'s
- <literal>Auto-defaults</literal> partition sizer will
- sometimes select smaller than adequate
- <filename class="directory">/var</filename> and
- <filename class="directory">/</filename> partitions.
+ <para>The <literal>Auto-defaults</literal> partition sizer
+ used by &man.sysinstall.8; will sometimes select smaller
+ than adequate <filename class="directory">/var</filename>
+ and <filename class="directory">/</filename> partitions.
Partition wisely and generously.</para>
</note>
</sect3>
@@ -182,25 +179,28 @@
<indexterm><primary>swap partition</primary></indexterm>
<para>As a rule of thumb, the swap partition should be about
- double the size of physical memory (RAM) as the kernel's
- virtual memory (VM) paging algorithms are tuned to perform
- best when the swap partition is at least two times
- the size of main memory. Systems with minimal RAM may
- perform better with more swap. Configuring too little swap
- can lead to inefficiencies in the VM page scanning code and
- might create issues later if more memory is added.</para>
-
- <para>On larger systems with multiple SCSI disks or multiple
- IDE disks operating on different controllers, it is
- recommended that swap be configured on each drive (up to
- four drives). The swap partitions should be approximately
- the same size. The kernel can handle arbitrary sizes but
- internal data structures scale to 4 times the largest swap
- partition. Keeping the swap partitions near the same size
- will allow the kernel to optimally stripe swap space across
- disks. Large swap sizes are fine, even if swap is not used
- much. It might be easier to recover from a runaway program
- before being forced to reboot.</para>
+ double the size of physical memory (<acronym>RAM</acronym>)
+ as the kernel's virtual memory (<acronym>VM</acronym>)
+ paging algorithms are tuned to perform best when the swap
+ partition is at least two times the size of main memory.
+ Systems with minimal <acronym>RAM</acronym> may perform
+ better with more swap. Configuring too little swap can
+ lead to inefficiencies in the <acronym>VM</acronym> page
+ scanning code and might create issues later if more memory
+ is added.</para>
+
+ <para>On larger systems with multiple <acronym>SCSI</acronym>
+ disks or multiple <acronym>IDE</acronym> disks operating
+ on different controllers, it is recommended that swap be
+ configured on each drive, up to four drives. The swap
+ partitions should be approximately the same size. The
+ kernel can handle arbitrary sizes but internal data
+ structures scale to 4 times the largest swap partition.
+ Keeping the swap partitions near the same size will allow
+ the kernel to optimally stripe swap space across disks.
+ Large swap sizes are fine, even if swap is not used much.
+ It might be easier to recover from a runaway program before
+ being forced to reboot.</para>
</sect3>
<sect3>
@@ -210,24 +210,24 @@
fine, but there are several reasons why this is a bad idea.
First, each partition has different operational
characteristics and separating them allows the file system
- to tune accordingly. For example, the root and
- <filename class="directory">/usr</filename> partitions are
+ to tune accordingly. For example, the root and <filename
+ class="directory">/usr</filename> partitions are
read-mostly, with few writes, while a lot of reads and
- writes could occur in
- <filename class="directory">/var</filename> and
- <filename class="directory">/var/tmp</filename>.</para>
+ writes could occur in <filename
+ class="directory">/var</filename> and <filename
+ class="directory">/var/tmp</filename>.</para>
<para>By properly partitioning a system, fragmentation
introduced in the smaller write heavy partitions will not
- bleed over into the mostly-read partitions. Keeping the
- write-loaded partitions closer to the disk's edge, will
+ bleed over into the mostly read partitions. Keeping the
+ write loaded partitions closer to the disk's edge will
increase I/O performance in the partitions where it occurs
- the most. Now while I/O performance in the larger
- partitions may be needed, shifting them more toward the edge
- of the disk will not lead to a significant performance
- improvement over moving
- <filename class="directory">/var</filename> to the edge.
- Finally, there are safety concerns. A smaller, neater root
+ the most. While I/O performance in the larger partitions
+ may be needed, shifting them more toward the edge of the
+ disk will not lead to a significant performance
+ improvement over moving <filename
+ class="directory">/var</filename> to the edge. Finally,
+ there are safety concerns. A smaller, neater root
partition which is mostly read-only has a greater chance of
surviving a bad crash.</para>
</sect3>
@@ -243,8 +243,8 @@
</indexterm>
<para>The principal location for system configuration information
- is <filename>/etc/rc.conf</filename>. This file contains
- a wide range of configuration information and it is read at
+ is <filename>/etc/rc.conf</filename>. This file contains a
+ wide range of configuration information and it is read at
system startup to configure the system. It provides the
configuration information for the <filename>rc*</filename>
files.</para>
@@ -261,8 +261,7 @@
system-specific configuration in order to keep administration
overhead down. The recommended approach is to place
system-specific configuration into
- <filename>/etc/rc.conf.local</filename>. For
- example:</para>
+ <filename>/etc/rc.conf.local</filename>. For example:</para>
<itemizedlist>
<listitem>
@@ -283,21 +282,20 @@ ifconfig_fxp0="inet 10.1.1.1/8"</programlisting>
</listitem>
</itemizedlist>
- <para><filename>rc.conf</filename> can then be
- distributed to every system using <command>rsync</command> or a
- similar program, while <filename>rc.conf.local</filename>
- remains unique.</para>
+ <para>Distribute <filename>/etc/rc.conf</filename> to every
+ system using <command>rsync</command> or a similar program,
+ while <filename>/etc/rc.conf.local</filename> remains
+ unique.</para>
<para>Upgrading the system using &man.sysinstall.8; or
<command>make world</command> will not overwrite
- <filename>rc.conf</filename>, so system configuration
+ <filename>/etc/rc.conf</filename>, so system configuration
information will not be lost.</para>
<tip>
- <para>The <filename>/etc/rc.conf</filename> configuration file
+ <para>The configuration in <filename>/etc/rc.conf</filename>
is parsed by &man.sh.1;. This allows system operators to
- add a certain amount of logic to this file, which may help to
- create very complex configuration scenarios. Refer to
+ create complex configuration scenarios. Refer to
&man.rc.conf.5; for further information on this topic.</para>
</tip>
</sect1>
@@ -313,17 +311,17 @@ ifconfig_fxp0="inet 10.1.1.1/8"</programlisting>
<indexterm><primary>/usr/local/etc</primary></indexterm>
- <para>Typically, these files are installed in
- <filename class="directory">/usr/local/etc</filename>. In the
- case where an application has a large number of configuration
+ <para>Typically, these files are installed in <filename
+ class="directory">/usr/local/etc</filename>. In the case
+ where an application has a large number of configuration
files, a subdirectory will be created to hold them.</para>
<para>Normally, when a port or package is installed, sample
configuration files are also installed. These are usually
- identified with a <filename>.default</filename> suffix. If
- there are no existing configuration files for the application,
- they will be created by copying the
- <filename>.default</filename> files.</para>
+ identified with a suffix such as <filename>.sample</filename>.
+ If there are no existing configuration files for the
+ application, they can be created by copying the sample
+ files.</para>
<para>For example, consider the contents of the directory
<filename
@@ -340,10 +338,10 @@ ifconfig_fxp0="inet 10.1.1.1/8"</programlisting>
-rw-r--r-- 1 root wheel 7980 May 20 1998 srm.conf
-rw-r--r-- 1 root wheel 7933 May 20 1998 srm.conf.default</literallayout>
- <para>The file sizes show that only
- <filename>srm.conf</filename> has been changed. A later
- update of the <application>Apache</application> port would not
- overwrite this changed file.</para>
+ <para>The file sizes show that only <filename>srm.conf</filename>
+ has been changed. A later update of the
+ <application>Apache</application> port would not overwrite
+ this changed file.</para>
</sect1>
<sect1 id="configtuning-starting-services">
@@ -363,10 +361,10 @@ ifconfig_fxp0="inet 10.1.1.1/8"</programlisting>
<para>Many users install third party software on &os; from the
Ports Collection and require the installed services to be
- started upon system initialization. Services,
- such as <filename role="package">mail/postfix</filename> or
- <filename role="package">www/apache22</filename> are just two of
- the many software packages which may be started during system
+ started upon system initialization. Services, such as
+ <filename role="package">mail/postfix</filename> or
+ <filename role="package">www/apache22</filename> are just two
+ of the many software packages which may be started during system
initialization. This section explains the procedures available
for starting third party software.</para>
@@ -378,13 +376,12 @@ ifconfig_fxp0="inet 10.1.1.1/8"</programlisting>
<para>Now that &os; includes <filename>rc.d</filename>,
configuration of application startup is easier and provides
- more features. Using the key words discussed in the
- <link linkend="configtuning-rcd">rc.d</link> section,
- applications can be set to start after certain other services
- and extra flags can be passed through
- <filename>/etc/rc.conf</filename> in place of hard coded flags
- in the start up script. A basic script may look similar to
- the following:</para>
+ more features. Using the key words discussed in <xref
+ linkend="configtuning-rcd"/>, applications can be set to
+ start after certain other services and extra flags can be
+ passed through <filename>/etc/rc.conf</filename> in place of
+ hard coded flags in the start up script. A basic script may
+ look similar to the following:</para>
<programlisting>#!/bin/sh
#
@@ -411,48 +408,42 @@ pidfile=${utility_pidfile-"/var/run/utility.pid"}
run_rc_command "$1"</programlisting>
<para>This script will ensure that the provided
- <application>utility</application> will be started after the
+ <literal>utility</literal> will be started after the
<literal>DAEMON</literal> pseudo-service. It also provides a
- method for setting and tracking the <acronym>PID</acronym>, or
- process <acronym>ID</acronym> file.</para>
+ method for setting and tracking the process ID
+ (<acronym>PID</acronym>).</para>
<para>This application could then have the following line placed
in <filename>/etc/rc.conf</filename>:</para>
<programlisting>utility_enable="YES"</programlisting>
- <para>This method also allows for easier manipulation of the
- command line arguments, inclusion of the default functions
- provided in <filename>/etc/rc.subr</filename>, compatibility
- with the &man.rcorder.8; utility and provides for easier
- configuration via <filename>rc.conf</filename>.</para>
+ <para>This method allows for easier manipulation of command
+ line arguments, inclusion of the default functions provided
+ in <filename>/etc/rc.subr</filename>, compatibility with
+ &man.rcorder.8;, and provides for easier configuration via
+ <filename>rc.conf</filename>.</para>
</sect2>
<sect2>
<title>Using Services to Start Services</title>
- <para>Other services, such as the <acronym>POP</acronym>3 server
- daemons or <acronym>IMAP</acronym>, could be started using
- &man.inetd.8;. This involves installing the service utility
- from the Ports Collection with a configuration line added to
- <filename>/etc/inetd.conf</filename>, or by
- uncommenting one of the current configuration lines. Working
- with <application>inetd</application> and its configuration is
- described in depth in the
- <link linkend="network-inetd">inetd</link> section.</para>
-
- <para>In some cases it may make more sense to use the
- &man.cron.8; daemon to start system services. This approach
- has a number of advantages because <command>cron</command>
- runs these processes as the <filename>crontab</filename>'s
- file owner. This allows regular users to start and maintain
- some applications.</para>
-
- <para>The <command>cron</command> utility provides a unique
- feature, <literal>@reboot</literal>, which may be used in
- place of the time specification. This will cause the job to
- be run when &man.cron.8; is started, normally during system
- initialization.</para>
+ <para>Other services can be started using &man.inetd.8;.
+ Working with &man.inetd.8; and its configuration is
+ described in depth in
+ <xref linkend="network-inetd"/>.</para>
+
+ <para>In some cases, it may make more sense to use
+ &man.cron.8; to start system services. This approach
+ has a number of advantages as &man.cron.8; runs these
+ processes as the owner of the &man.crontab.5;. This allows
+ regular users to start and maintain their own
+ applications.</para>
+
+ <para>The <literal>@reboot</literal> feature of &man.cron.8;,
+ may be used in place of the time specification. This causes
+ the job to run when &man.cron.8; is started, normally during
+ system initialization.</para>
</sect2>
</sect1>
@@ -467,7 +458,7 @@ run_rc_command "$1"</programlisting>
</author>
</authorgroup>
</sect1info>
- <title>Configuring the <command>cron</command> Utility</title>
+ <title>Configuring &man.cron.8;</title>
<indexterm><primary>cron</primary>
<secondary>configuration</secondary></indexterm>
@@ -475,20 +466,20 @@ run_rc_command "$1"</programlisting>
<para>One of the most useful utilities in &os; is &man.cron.8;.
This utility runs in the background and regularly checks
<filename>/etc/crontab</filename> for tasks to execute and
- searches
- <filename class="directory">/var/cron/tabs</filename> for custom
- <filename>crontab</filename> files. These files store
- information about specific functions which
- <command>cron</command> is supposed to perform at certain
- times.</para>
-
- <para>The <command>cron</command> utility uses two different types
- of configuration files, the system crontab and user crontabs.
- These formats only differ in the sixth field and later. In the
- system crontab, <command>cron</command> will run the command as
- the user specified in the sixth field. In a user crontab, all
- commands run as the user who created the crontab, so the sixth
- field is the last field; this is an important security feature.
+ searches <filename class="directory">/var/cron/tabs</filename>
+ for custom &man.crontab.5; files. These files store
+ information about specific functions which &man.cron.8; is
+ supposed to perform at certain times.</para>
+
+ <para>Two different types of configuration files are used by
+ &man.cron.8;: the system <filename>crontab</filename> and user
+ <filename>crontab</filename>s. These formats only differ in
+ the sixth field and later. In the system
+ <filename>crontab</filename>, &man.cron.8; runs the command as
+ the user specified in the sixth field. In a user
+ <filename>crontab</filename>, all commands run as the user who
+ created the <filename>crontab</filename>, so the sixth field
+ is the last field; this is an important security feature.
The final field is always the command to run.</para>
<note>
@@ -497,31 +488,30 @@ run_rc_command "$1"</programlisting>
Commands in a user's crontab run with the permissions of the
user who owns the crontab.</para>
- <para>The <username>root</username> user can have a user crontab
- just like any other user. The <username>root</username> user
- crontab is separate from <filename>/etc/crontab</filename>
- (the system crontab). Because the system crontab effectively
- invokes the specified commands as root there is usually no
- need to create a user crontab for
+ <para>The <username>root</username> user can have a user
+ <filename>crontab</filename> just like any other user. The
+ <username>root</username> user <filename>crontab</filename>
+ is separate from the system <filename>crontab</filename>,
+ <filename>/etc/crontab</filename>. Because the system
+ <filename>crontab</filename> invokes the specified commands as
+ <username>root</username>, there is usually no need to create
+ a user <filename>crontab</filename> for
<username>root</username>.</para>
</note>
- <para>Let us take a look at <filename>/etc/crontab</filename>,
- the system crontab:</para>
+ <para>Here is a sample entry from
+ <filename>/etc/crontab</filename>:</para>
- <programlisting># /etc/crontab - root's crontab for &os;
+ <programlisting># /etc/crontab - root's crontab for FreeBSD
#
-# &dollar;&os;: src/etc/crontab,v 1.32 2002/11/22 16:13:39 tom Exp &dollar;
+# $FreeBSD$
# <co id="co-comments"/>
#
SHELL=/bin/sh
PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin <co id="co-env"/>
-HOME=/var/log
-#
#
#minute hour mday month wday who command <co id="co-field-descr"/>
#
-#
*/5 * * * * root /usr/libexec/atrun <co id="co-main"/></programlisting>
<calloutlist>
@@ -536,52 +526,46 @@ HOME=/var/log
</callout>
<callout arearefs="co-env">
- <para>First, the environment must be defined. The equals
- (<literal>=</literal>) character is used to define any
- environment settings, as with this example where it is used
- for the <envar>SHELL</envar>, <envar>PATH</envar>, and
- <envar>HOME</envar> options. If the shell line is omitted,
- <command>cron</command> will use the default, which is
- <command>sh</command>. If the <envar>PATH</envar> variable
- is omitted, no default will be used and file locations will
- need to be absolute. If <envar>HOME</envar> is omitted,
- <command>cron</command> will use the invoking users home
- directory.</para>
+ <para>The equals (<literal>=</literal>) character is used to
+ define any environment settings. In this example, it is
+ used to define the <envar>SHELL</envar> and
+ <envar>PATH</envar>. If the <envar>SHELL</envar> is
+ omitted, &man.cron.8; will use the default of &man.sh.1;.
+ If the <envar>PATH</envar> is omitted, no default will be
+ used and file locations will need to be absolute.</para>
</callout>
<callout arearefs="co-field-descr">
- <para>This line defines a total of seven fields. Listed here
- are the values <literal>minute</literal>,
+ <para>This line defines a total of seven fields:
+ <literal>minute</literal>,
<literal>hour</literal>, <literal>mday</literal>,
<literal>month</literal>, <literal>wday</literal>,
<literal>who</literal>, and <literal>command</literal>.
These are almost all self explanatory.
- <literal>minute</literal> is the time in minutes the command
- will be run. <literal>hour</literal> is similar to the
- <literal>minute</literal> option, just in hours.
- <literal>mday</literal> stands for day of the month.
- <literal>month</literal> is similar to
- <literal>hour</literal> and <literal>minute</literal>, as it
- designates the month. The <literal>wday</literal> option
- stands for day of the week. All these fields must be
- numeric values, and follow the twenty-four hour clock. The
- <literal>who</literal> field is special, and only exists in
- <filename>/etc/crontab</filename>. This field specifies
- which user the command should be run as. The last field is
- the command to be executed.</para>
+ <literal>minute</literal> is the time in minutes when the
+ specified command will be run. <literal>hour</literal> is
+ the hour when the specified command will be run.
+ <literal>mday</literal> stands for day of the month and
+ <literal>month</literal> designates the month. The
+ <literal>wday</literal> option stands for day of the week.
+ These fields must be numeric values, representing the
+ twenty-four hour clock, or a <literal>*</literal>,
+ representing all values for that field. The
+ <literal>who</literal> field only exists in the system
+ crontab. This field specifies which user the command
+ should be run as. The last field is the command to be
+ executed.</para>
</callout>
<callout arearefs="co-main">
- <para>This last line will define the values discussed above.
+ <para>This last line defines the values discussed above.
This example has a <literal>*/5</literal> listing,followed
by several more <literal>*</literal> characters. These
<literal>*</literal> characters mean
<quote>first-last</quote>, and can be interpreted as
<emphasis>every</emphasis> time. In this example,
- <command>atrun</command> is invoked by
- <username>root</username> every five minutes regardless of
- the day or month. For more information on
- <command>atrun</command>, refer to &man.atrun.8;.</para>
+ &man.atrun.8; is invoked by <username>root</username>
+ every five minutes, regardless of the day or month.</para>
<para>Commands can have any number of flags passed to them;
however, commands which extend to multiple lines need to be
@@ -590,50 +574,47 @@ HOME=/var/log
</callout>
</calloutlist>
- <para>This is the basic setup for every
- <filename>crontab</filename>, although there is one thing
- different about this one. Field number six, which specifies
- the username, only exists in the system
- <filename>crontab</filename>. This field should be omitted for
- individual user <filename>crontab</filename> files.</para>
+ <para>This is the basic setup for every &man.crontab.5;.
+ However, field number six, which specifies the username, only
+ exists in the system &man.crontab.5;. This field should be
+ omitted for individual user &man.crontab.5; files.</para>
<sect2 id="configtuning-installcrontab">
<title>Installing a Crontab</title>
<important>
<para>Do not use the procedure described here to edit and
- install the system crontab,
+ install the system <filename>crontab</filename>,
<filename>/etc/crontab</filename>. Instead, use an
- editor: <command>cron</command> will notice that the file
- has changed and immediately begin using the updated version.
+ editor and &man.cron.8; will notice that the file has
+ changed and immediately begin using the updated version.
See <ulink
url="&url.books.faq;/admin.html#root-not-found-cron-errors">
this FAQ entry</ulink> for more information.</para>
</important>
- <para>To install a freshly written user
- <filename>crontab</filename>, first use an editor to create
- and save a file in the proper format. Then, specify the file
- name with <command>crontab</command>:</para>
+ <para>To install a freshly written user &man.crontab.5;, use
+ an editor to create and save a file in the proper format.
+ Then, specify the file name with &man.crontab.1;:</para>
<screen>&prompt.user; <userinput>crontab crontab-file</userinput></screen>
<para>In this example, <filename>crontab-file</filename> is the
- filename of a <filename>crontab</filename> that was previously
+ filename of a &man.crontab.5; that was previously
created.</para>
- <para>To list installed <filename>crontab</filename> files, pass
- <option>-l</option> to <command>crontab</command>.</para>
+ <para>To list installed &man.crontab.5; files, pass
+ <option>-l</option> to &man.crontab.1;.</para>
- <para>For users who wish to begin their own crontab file from
- scratch, without the use of a template, the
- <command>crontab -e</command> option is available. This will
- invoke the selected editor with an empty file. When the file
- is saved, it will be automatically installed by
- <command>crontab</command>.</para>
+ <para>Users who wish to begin their own
+ <filename>crontab</filename> file from scratch, without the
+ use of a template, can use <command>crontab -e</command>. This
+ will invoke the default editor with an empty file. When this
+ file is saved, it will be automatically installed by
+ &man.crontab.1;.</para>
- <para>In order to remove a user <filename>crontab</filename>
- completely, use <command>crontab -r</command>.</para>
+ <para>In order to remove a user &man.crontab.5; completely,
+ use <command>crontab -r</command>.</para>
</sect2>
</sect1>
@@ -651,105 +632,102 @@ HOME=/var/log
<title>Using &man.rc.8; Under &os;</title>
- <para>In 2002 &os; integrated the NetBSD <filename>rc.d</filename>
- system for system initialization. Users should notice the files
- listed in the <filename class="directory">/etc/rc.d</filename>
- directory. Many of these files are for basic services which can
- be controlled with the <option>start</option>,
- <option>stop</option>, and <option>restart</option> options.
- For instance, &man.sshd.8; can be restarted with the following
- command:</para>
+ <para>In 2002, &os; integrated the NetBSD &man.rc.8; system for
+ system initialization. The files listed in <filename
+ class="directory">/etc/rc.d</filename> provide basic services
+ which can be controlled with the <option>start</option>,
+ <option>stop</option>, and <option>restart</option> options
+ to &man.service.8;. For instance, &man.sshd.8; can be restarted
+ with the following command:</para>
<screen>&prompt.root; <userinput>service sshd restart</userinput></screen>
- <para>This procedure is similar for other services. Of course,
- services are usually started automatically at boot time as
- specified in &man.rc.conf.5;. For example, enabling the Network
- Address Translation daemon at startup is as simple as adding the
- following line to <filename>/etc/rc.conf</filename>:</para>
+ <para>This procedure can be used to start services on a running
+ system. Services will be started automatically at boot time
+ as specified in &man.rc.conf.5;. For example, to enable
+ &man.natd.8; at system startup, add the following line to
+ <filename>/etc/rc.conf</filename>:</para>
<programlisting>natd_enable="YES"</programlisting>
<para>If a <option>natd_enable="NO"</option> line is already
- present, then simply change the <option>NO</option> to
- <option>YES</option>. The rc scripts will automatically load
- any other dependent services during the next reboot, as
- described below.</para>
-
- <para>Since the <filename>rc.d</filename> system is primarily
- intended to start/stop services at system startup/shutdown time,
- the standard <option>start</option>, <option>stop</option> and
+ present, change the <literal>NO</literal> to
+ <literal>YES</literal>. The &man.rc.8; scripts will
+ automatically load any dependent services during the next boot,
+ as described below.</para>
+
+ <para>Since the &man.rc.8; system is primarily intended to start
+ and stop services at system startup and shutdown time, the
+ <option>start</option>, <option>stop</option> and
<option>restart</option> options will only perform their action
- if the appropriate <filename>/etc/rc.conf</filename> variables
- are set. For instance, <command>sshd restart</command> will
+ if the appropriate <filename>/etc/rc.conf</filename> variable
+ is set. For instance, <command>sshd restart</command> will
only work if <varname>sshd_enable</varname> is set to
<option>YES</option> in <filename>/etc/rc.conf</filename>.
To <option>start</option>, <option>stop</option> or
- <option>restart</option> a service regardless of the settings in
- <filename>/etc/rc.conf</filename>, the commands should be
+ <option>restart</option> a service regardless of the settings
+ in <filename>/etc/rc.conf</filename>, these commands should be
prefixed with <quote>one</quote>. For instance, to restart
- <command>sshd</command> regardless of the current
+ &man.sshd.8; regardless of the current
<filename>/etc/rc.conf</filename> setting, execute the following
command:</para>
<screen>&prompt.root; <userinput>service sshd onerestart</userinput></screen>
- <para>It is easy to check if a service is enabled in
- <filename>/etc/rc.conf</filename> by running the appropriate
- <filename>rc.d</filename> script with the option
- <option>rcvar</option>. Thus, an administrator can check that
- <command>sshd</command> is in fact enabled in
- <filename>/etc/rc.conf</filename> by running:</para>
+ <para>To check if a service is enabled in
+ <filename>/etc/rc.conf</filename>, run the appropriate
+ &man.rc.8; script with <option>rcvar</option>. This example
+ checks to see if &man.sshd.8; is enabled in
+ <filename>/etc/rc.conf</filename>:</para>
<screen>&prompt.root; <userinput>service sshd rcvar</userinput>
# sshd
$sshd_enable=YES</screen>
<note>
- <para>The second line (<literal># sshd</literal>) is the output
- from <command>sshd</command>, not a
- <username>root</username> console.</para>
+ <para>The <literal># sshd</literal> line is output from the
+ above command, not a <username>root</username> console.</para>
</note>
<para>To determine whether or not a service is running, use
<option>status</option>. For instance, to verify that
- <command>sshd</command> is running:</para>
+ &man.sshd.8; is running:</para>
<screen>&prompt.root; <userinput>service sshd status</userinput>
sshd is running as pid 433.</screen>
- <para>In some cases it is also possible to <option>reload</option>
- a service. This will attempt to send a signal to an individual
- service, forcing the service to reload its configuration files.
- In most cases this means sending the service a
- <literal>SIGHUP</literal> signal. Support for this feature is
- not included for every service.</para>
+ <para>In some cases, it is also possible to
+ <option>reload</option> a service. This attempts to send a
+ signal to an individual service, forcing the service to reload
+ its configuration files. In most cases, this means sending
+ the service a <literal>SIGHUP</literal> signal. Support for
+ this feature is not included for every service.</para>
- <para>The <filename>rc.d</filename> system is not only used for
- network services, it also contributes to most of the system
- initialization. For instance, when the
- <filename>bgfsck</filename> script is executed, it will print
- out the following message:</para>
+ <para>The &man.rc.8; system is used for network services and it
+ also contributes to most of the system initialization. For
+ instance, when the
+ <filename>/etc/rc.d/bgfsck</filename> script is executed, it
+ prints out the following message:</para>
<screen>Starting background file system checks in 60 seconds.</screen>
- <para>Therefore this file is used for background file system
- checks, which are done only during system initialization.</para>
+ <para>This script is used for background file system checks,
+ which occur only during system initialization.</para>
<para>Many system services depend on other services to function
- properly. For example, NIS and other RPC-based services may
- fail to start until after the <command>rpcbind</command>
- (portmapper) service has started. To resolve this issue,
- information about dependencies and other meta-data is included
- in the comments at the top of each startup script. The
- &man.rcorder.8; program is then used to parse these comments
+ properly. For example, &man.yp.8; and other
+ <acronym>RPC</acronym>-based services may fail to start until
+ after the &man.rpcbind.8; service has started. To resolve this
+ issue, information about dependencies and other meta-data is
+ included in the comments at the top of each startup script.
+ The &man.rcorder.8; program is used to parse these comments
during system initialization to determine the order in which
system services should be invoked to satisfy the
dependencies.</para>
- <para>The following words must be included in all startup scripts
- (they are required by &man.rc.subr.8; to <quote>enable</quote>
- the startup script):</para>
+ <para>The following key word must be included in all startup
+ scripts as it is required by &man.rc.subr.8; to
+ <quote>enable</quote> the startup script:</para>
<itemizedlist>
<listitem>
@@ -758,34 +736,36 @@ sshd is running as pid 433.</screen>
</listitem>
</itemizedlist>
- <para>The following words may be included at the top of each
- startup file. They are not strictly necessary, but they are
+ <para>The following key words may be included at the top of each
+ startup script. They are not strictly necessary, but are
useful as hints to &man.rcorder.8;:</para>
<itemizedlist>
<listitem>
<para><literal>REQUIRE</literal>: Lists services which are
- required for this service. This file will run
- <emphasis>after</emphasis> the specified services.</para>
+ required for this service. The script containing this key
+ word will run <emphasis>after</emphasis> the specified
+ services.</para>
</listitem>
<listitem>
<para><literal>BEFORE</literal>: Lists services which depend
- on this service. This file will run
- <emphasis>before</emphasis> the specified services.</para>
+ on this service. The script containing this key word will
+ run <emphasis>before</emphasis> the specified
+ services.</para>
</listitem>
</itemizedlist>
<para>By carefully setting these keywords for each startup script,
- an administrator has a very fine-grained level of control of the
- startup order of the scripts, without the hassle of
- <quote>runlevels</quote> like some other &unix; operating
+ an administrator has a fine-grained level of control of the
+ startup order of the scripts, without the need for
+ <quote>runlevels</quote> used by some &unix; operating
systems.</para>
- <para>Additional information about the <filename>rc.d</filename>
- system can be found in &man.rc.8; and &man.rc.subr.8;. Refer to
- <ulink url="&url.articles.rc-scripting;">this article</ulink> for
- instructions on how to create custom <filename>rc.d</filename>
+ <para>Additional information can be found in &man.rc.8; and
+ &man.rc.subr.8;. Refer to <ulink
+ url="&url.articles.rc-scripting;">this article</ulink> for
+ instructions on how to create custom &man.rc.8;
scripts.</para>
</sect1>
@@ -808,8 +788,9 @@ sshd is running as pid 433.</screen>
<secondary>configuration</secondary>
</indexterm>
- <para>Adding and configuring a network card is a common task for
- any &os; administrator.</para>
+ <para>Adding and configuring a network interface card
+ (<acronym>NIC</acronym>) is a common task for any &os;
+ administrator.</para>
<sect2>
<title>Locating the Correct Driver</title>
@@ -819,24 +800,27 @@ sshd is running as pid 433.</screen>
<secondary>driver</secondary>
</indexterm>
- <para>First, determine the model of the network interface card
- and the chip it uses. &os; supports a wide variety of network
- interface cards. Check the Hardware Compatibility List for
- the &os; release to see if the card is supported.</para>
+ <para>First, determine the model of the <acronym>NIC</acronym>
+ and the chip it uses. &os; supports a wide variety of
+ <acronym>NIC</acronym>s. Check the Hardware Compatibility
+ List for the &os; release to see if the <acronym>NIC</acronym>
+ is supported.</para>
- <para>If the card is supported, determine the name of the &os;
- driver for the card. Refer to
- <filename>/usr/src/sys/conf/NOTES</filename> and
+ <para>If the <acronym>NIC</acronym> is supported, determine
+ the name of the &os; driver for the <acronym>NIC</acronym>.
+ Refer to <filename>/usr/src/sys/conf/NOTES</filename> and
<filename>/usr/src/sys/<replaceable>arch</replaceable>/conf/NOTES</filename>
- for the list of network interface drivers with some
+ for the list of <acronym>NIC</acronym> drivers with some
information about the supported chipsets. When in doubt, read
the manual page of the driver as it will provide more
information about the supported hardware and any known
limitations of the driver.</para>
- <para>The drivers for common network cards are already present
- in the <filename>GENERIC</filename> kernel, meaning the card
- should show up during boot, as in this example:</para>
+ <para>The drivers for common <acronym>NIC</acronym>s are
+ already present in the <filename>GENERIC</filename> kernel,
+ meaning the <acronym>NIC</acronym> should show up during boot.
+ In this example, two <acronym>NIC</acronym>s using the
+ &man.dc.4; driver are present on the system:</para>
<screen>dc0: &lt;82c169 PNIC 10/100BaseTX&gt; port 0xa000-0xa0ff mem 0xd3800000-0xd38
000ff irq 15 at device 11.0 on pci0
@@ -853,52 +837,49 @@ bmtphy1: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto
dc1: Ethernet address: 00:a0:cc:da:da:db
dc1: [ITHREAD]</screen>
- <para>In this example, two cards using the &man.dc.4; driver are
- present on the system.</para>
-
- <para>If the driver for the interface is not present in
- <filename>GENERIC</filename>, but a driver is available, the
- driver will need to be loaded before the interface can be
- configured and used. This may be accomplished in one of two
- ways:</para>
+ <para>If the driver for the <acronym>NIC</acronym> is not
+ present in <filename>GENERIC</filename>, but a driver is
+ available, the driver will need to be loaded before the
+ <acronym>NIC</acronym> can be configured and used. This may
+ be accomplished in one of two ways:</para>
<itemizedlist>
<listitem>
<para>The easiest way is to load a kernel module for the
- network card with &man.kldload.8;. To also automatically
- load the driver at boot time, add the appropriate line to
- <filename>/boot/loader.conf</filename>. Not all NIC
- drivers are available as modules; notable examples of
- devices for which modules do not exist are ISA
- cards.</para>
+ <acronym>NIC</acronym> using &man.kldload.8;. To also
+ automatically load the driver at boot time, add the
+ appropriate line to
+ <filename>/boot/loader.conf</filename>. Not all
+ <acronym>NIC</acronym> drivers are available as
+ modules.</para>
</listitem>
<listitem>
- <para>Alternatively, statically compile support for the card
- into a custom kernel. Refer to
+ <para>Alternatively, statically compile support for the
+ <acronym>NIC</acronym> into a custom kernel. Refer to
<filename>/usr/src/sys/conf/NOTES</filename>,
<filename>/usr/src/sys/<replaceable>arch</replaceable>/conf/NOTES</filename>
and the manual page of the driver to determine which line
to add to the custom kernel configuration file. For more
- information about recompiling the kernel, refer to
- <xref linkend="kernelconfig"/>. If the card was detected
- at boot, the kernel does not need to be recompiled.</para>
+ information about recompiling the kernel, refer to <xref
+ linkend="kernelconfig"/>. If the
+ <acronym>NIC</acronym> was detected at boot, the kernel
+ does not need to be recompiled.</para>
</listitem>
</itemizedlist>
<sect3 id="config-network-ndis">
- <title>Using &windows; NDIS Drivers</title>
+ <title>Using &windows; <acronym>NDIS</acronym> Drivers</title>
- <indexterm><primary>NDIS</primary></indexterm>
+ <indexterm><primary><acronym>NDIS</acronym></primary></indexterm>
<indexterm><primary>NDISulator</primary></indexterm>
<indexterm><primary>&windows; drivers</primary></indexterm>
- <indexterm><primary>Microsoft Windows</primary></indexterm>
- <indexterm>
- <primary>Microsoft Windows</primary>
+ <indexterm><primary>&microsoft.windows;</primary>
<secondary>device drivers</secondary>
</indexterm>
<indexterm>
- <primary>KLD (kernel loadable object)</primary>
+ <primary><acronym>KLD</acronym> (kernel loadable
+ object)</primary>
</indexterm>
<!-- We should probably omit the expanded name, and add a <see> entry
for it. Whatever is done must also be done to the same indexterm in
@@ -908,45 +889,44 @@ linuxemu/chapter.xml -->
provide schematics for their drivers to the open source
community because they regard such information as trade
secrets. Consequently, the developers of &os; and other
- operating systems are left two choices: develop the drivers
- by a long and pain-staking process of reverse engineering or
- using the existing driver binaries available for the
- &microsoft.windows; platforms. Most developers, including
- those involved with &os;, have taken the latter
- approach.</para>
-
- <para>Thanks to the contributions of Bill Paul (wpaul) there
- is <quote>native</quote> support for the Network Driver
- Interface Specification (NDIS). The &os; NDISulator
- (otherwise known as Project Evil) takes a &windows; driver
- binary and basically tricks it into thinking it is running
- on &windows;. Because the &man.ndis.4; driver is using a
- &windows; binary, it only runs on &i386; and amd64 systems.
- PCI, CardBus, PCMCIA (PC-Card), and USB devices are
- supported.</para>
-
- <para>To use the NDISulator, three things are needed:</para>
+ operating systems are left with two choices: develop the
+ drivers by a long and pain-staking process of reverse
+ engineering or using the existing driver binaries available
+ for &microsoft.windows; platforms.</para>
+
+ <para>&os; provides <quote>native</quote> support for the
+ Network Driver Interface Specification
+ (<acronym>NDIS</acronym>). It includes &man.ndisgen.8;
+ which can be used to convert a &windowsxp; driver into a
+ format that can be used on &os;. Because the &man.ndis.4;
+ driver uses a &windowsxp; binary, it only runs on &i386;
+ and amd64 systems. <acronym>PCI</acronym>, CardBus,
+ <acronym>PCMCIA</acronym>, and <acronym>USB</acronym>
+ devices are supported.</para>
+
+ <para>To use &man.ndisgen.8;, three things are needed:</para>
<orderedlist>
<listitem>
- <para>Kernel sources</para>
+ <para>&os; kernel sources.</para>
</listitem>
<listitem>
- <para>&windowsxp; driver binary
- (<filename>.SYS</filename> extension)</para>
+ <para>A &windowsxp; driver binary with a
+ <filename>.SYS</filename> extension.</para>
</listitem>
<listitem>
- <para>&windowsxp; driver configuration file
- (<filename>.INF</filename> extension)</para>
+ <para>A &windowsxp; driver configuration file with a
+ <filename>.INF</filename> extension.</para>
</listitem>
</orderedlist>
- <para>Locate the files for the specific card. Generally,
- they can be found on the included CDs or at the vendor's
- website. The following examples use
- <filename>W32DRIVER.SYS</filename> and
+ <para>Download the <filename>.SYS</filename> and
+ <filename>.INF</filename> files for the specific
+ <acronym>NIC</acronym>. Generally, these can be found on
+ the driver CD or at the vendor's website. The following
+ examples use <filename>W32DRIVER.SYS</filename> and
<filename>W32DRIVER.INF</filename>.</para>
<para>The driver bit width must match the version of &os;.
@@ -959,10 +939,10 @@ linuxemu/chapter.xml -->
<screen>&prompt.root; <userinput>ndisgen <replaceable>/path/to/W32DRIVER.INF</replaceable> <replaceable>/path/to/W32DRIVER.SYS</replaceable></userinput></screen>
- <para>&man.ndisgen.8; is interactive and prompts for any extra
- information it requires. A new kernel module is written in
- the current directory. Use &man.kldload.8; to load the new
- module:</para>
+ <para>This command is interactive and prompts for any extra
+ information it requires. A new kernel module will be
+ generated in the current directory. Use &man.kldload.8;
+ to load the new module:</para>
<screen>&prompt.root; <userinput>kldload <replaceable>./W32DRIVER_SYS.ko</replaceable></userinput></screen>
@@ -976,12 +956,12 @@ linuxemu/chapter.xml -->
<screen>&prompt.root; <userinput>kldload ndis</userinput>
&prompt.root; <userinput>kldload if_ndis</userinput></screen>
- <para>The first command loads the NDIS miniport driver
- wrapper, the second loads the actual network
- interface.</para>
+ <para>The first command loads the &man.ndis.4; miniport driver
+ wrapper and the second loads the generated
+ <acronym>NIC</acronym> driver.</para>
- <para>Now, check &man.dmesg.8; to see if there were any errors
- loading. If all went well, the output should be similar to
+ <para>Check &man.dmesg.8; to see if there were any load
+ errors. If all went well, the output should be similar to
the following:</para>
<screen>ndis0: &lt;Wireless-G PCI Adapter&gt; mem 0xf4100000-0xf4101fff irq 3 at device 8.0 on pci1
@@ -990,15 +970,14 @@ ndis0: Ethernet address: 0a:b1:2c:d3:4e:f5
ndis0: 11b rates: 1Mbps 2Mbps 5.5Mbps 11Mbps
ndis0: 11g rates: 6Mbps 9Mbps 12Mbps 18Mbps 36Mbps 48Mbps 54Mbps</screen>
- <para>From here you can treat the
- <devicename>ndis0</devicename> device like any other network
- interface (e.g., <devicename>dc0</devicename>).</para>
+ <para>From here, <devicename>ndis0</devicename> can be
+ configured like any other <acronym>NIC</acronym>.</para>
- <para>To configure the system to load the NDIS modules at
- boot time, copy the generated module,
- <filename>W32DRIVER_SYS.ko</filename>, to the <filename
- class="directory">/boot/modules</filename> directory. Then,
- add the following line to
+ <para>To configure the system to load the &man.ndis.4; modules
+ at boot time, copy the generated module,
+ <filename>W32DRIVER_SYS.ko</filename>, to <filename
+ class="directory">/boot/modules</filename>. Then, add the
+ following line to
<filename>/boot/loader.conf</filename>:</para>
<programlisting>W32DRIVER_SYS_load="YES"</programlisting>
@@ -1013,12 +992,12 @@ ndis0: 11g rates: 6Mbps 9Mbps 12Mbps 18Mbps 36Mbps 48Mbps 54Mbps</screen>
<secondary>configuration</secondary>
</indexterm>
- <para>Once the right driver is loaded for the network card, the
- card needs to be configured. As with many other things, the
- network card may have been configured at installation time by
- <application>sysinstall</application>.</para>
+ <para>Once the right driver is loaded for the
+ <acronym>NIC</acronym>, the card needs to be configured. It
+ may have been configured at installation time by
+ &man.sysinstall.8;.</para>
- <para>To display the configuration for the network interfaces,
+ <para>To display the <acronym>NIC</acronym> configuration,
enter the following command:</para>
<screen>&prompt.user; <userinput>ifconfig</userinput>
@@ -1047,28 +1026,29 @@ lo0: flags=8049&lt;UP,LOOPBACK,RUNNING,MULTICAST&gt; metric 0 mtu 16384
<itemizedlist>
<listitem>
<para><devicename>dc0</devicename>: The first Ethernet
- interface</para>
+ interface.</para>
</listitem>
<listitem>
<para><devicename>dc1</devicename>: The second Ethernet
- interface</para>
+ interface.</para>
</listitem>
<listitem>
<para><devicename>lo0</devicename>: The loopback
- device</para>
+ device.</para>
</listitem>
</itemizedlist>
<para>&os; uses the driver name followed by the order in which
- one the card is detected at the kernel boot to name the
- network card. For example <devicename>sis2</devicename> would
- be the third network card on the system using the &man.sis.4;
+ the card is detected at boot to name the
+ <acronym>NIC</acronym>. For example,
+ <devicename>sis2</devicename> is the third
+ <acronym>NIC</acronym> on the system using the &man.sis.4;
driver.</para>
- <para>In this example, the <devicename>dc0</devicename> device
- is up and running. The key indicators are:</para>
+ <para>In this example, <devicename>dc0</devicename> is up and
+ running. The key indicators are:</para>
<orderedlist>
<listitem>
@@ -1078,32 +1058,33 @@ lo0: flags=8049&lt;UP,LOOPBACK,RUNNING,MULTICAST&gt; metric 0 mtu 16384
<listitem>
<para>The card has an Internet (<literal>inet</literal>)
- address (in this case
- <hostid role="ipaddr">192.168.1.3</hostid>).</para>
+ address, <hostid
+ role="ipaddr">192.168.1.3</hostid>.</para>
</listitem>
<listitem>
<para>It has a valid subnet mask
- (<literal>netmask</literal>;
- <hostid role="netmask">0xffffff00</hostid> is the same as
- <hostid role="netmask">255.255.255.0</hostid>).</para>
+ (<literal>netmask</literal>), where <hostid
+ role="netmask">0xffffff00</hostid> is the same as
+ <hostid role="netmask">255.255.255.0</hostid>.</para>
</listitem>
<listitem>
- <para>It has a valid broadcast address (in this case,
- <hostid role="ipaddr">192.168.1.255</hostid>).</para>
+ <para>It has a valid broadcast address, <hostid
+ role="ipaddr">192.168.1.255</hostid>.</para>
</listitem>
<listitem>
- <para>The MAC address of the card (<literal>ether</literal>)
- is <hostid role="mac">00:a0:cc:da:da:da</hostid></para>
+ <para>The <acronym>MAC</acronym> address of the card
+ (<literal>ether</literal>) is <hostid
+ role="mac">00:a0:cc:da:da:da</hostid>.</para>
</listitem>
<listitem>
<para>The physical media selection is on autoselection mode
(<literal>media: Ethernet autoselect (100baseTX
&lt;full-duplex&gt;)</literal>). In this example,
- <devicename>dc1</devicename> was configured to run with
+ <devicename>dc1</devicename> is configured to run with
<literal>10baseT/UTP</literal> media. For more
information on available media types for a driver, refer
to its manual page.</para>
@@ -1130,41 +1111,40 @@ lo0: flags=8049&lt;UP,LOOPBACK,RUNNING,MULTICAST&gt; metric 0 mtu 16384
<para>it would indicate the card has not been configured.</para>
- <para>To configure the card, you will need
- <username>root</username> privileges. The network card
- configuration can be performed from the command line with
- &man.ifconfig.8; but will not persist after a reboot unless
- the network card's configuration is also added to
- <filename>/etc/rc.conf</filename> using an editor. Add a
- line for each network card present on the system, as seen in
+ <para>The card must be configured as <username>root</username>.
+ The <acronym>NIC</acronym> configuration can be performed
+ from the command line with &man.ifconfig.8; but will not
+ persist after a reboot unless the configuration is also added
+ to <filename>/etc/rc.conf</filename>. Add a line for each
+ <acronym>NIC</acronym> present on the system, as seen in
this example:</para>
<programlisting>ifconfig_dc0="inet 192.168.1.3 netmask 255.255.255.0"
ifconfig_dc1="inet 10.0.0.1 netmask 255.255.255.0 media 10baseT/UTP"</programlisting>
<para>Replace <devicename>dc0</devicename> and
- <devicename>dc1</devicename> and the IP address information
- with the correct values for the system.
- Refer to the man page for the driver, &man.ifconfig.8; and
+ <devicename>dc1</devicename> and the <acronym>IP</acronym>
+ address information with the correct values for the system.
+ Refer to the man page for the driver, &man.ifconfig.8;, and
&man.rc.conf.5; for more details about the allowed options and
the syntax of <filename>/etc/rc.conf</filename>.</para>
<para>If the network was configured during installation, some
- lines about the network card(s) may be already present.
- Double check <filename>/etc/rc.conf</filename> before adding
- any lines.</para>
-
- <para>If the network is not using DNS, edit
- <filename>/etc/hosts</filename> to add the names and the IP
- addresses of various machines of the LAN, if they are not
- already there. For more information, refer to &man.hosts.5;
- and to
+ entries for the <acronym>NIC</acronym>(s) may be already
+ present. Double check <filename>/etc/rc.conf</filename>
+ before adding any lines.</para>
+
+ <para>If the network is not using <acronym>DNS</acronym>, edit
+ <filename>/etc/hosts</filename> to add the names and
+ <acronym>IP</acronym> addresses of of the hosts on the
+ <acronym>LAN</acronym>, if they are not already there. For
+ more information, refer to &man.hosts.5; and to
<filename>/usr/share/examples/etc/hosts</filename>.</para>
<note>
- <para>If there is no DHCP server and access to the Internet is
- needed, manually configure the default gateway and the
- nameserver:</para>
+ <para>If there is no <acronym>DHCP</acronym> server and
+ access to the Internet is needed, manually configure the
+ default gateway and the nameserver:</para>
<screen>&prompt.root; <userinput>echo 'defaultrouter="<replaceable>your_default_router</replaceable>"' &gt;&gt; /etc/rc.conf</userinput>
&prompt.root; <userinput>echo 'nameserver <replaceable>your_DNS_server</replaceable>' &gt;&gt; /etc/resolv.conf</userinput></screen>
@@ -1174,7 +1154,7 @@ ifconfig_dc1="inet 10.0.0.1 netmask 255.255.255.0 media 10baseT/UTP"</programlis
<sect2>
<title>Testing and Troubleshooting</title>
- <para>Once the necessary changes in
+ <para>Once the necessary changes to
<filename>/etc/rc.conf</filename> are saved, a reboot can be
used to test the network configuration and to verify that the
system restarts without any configuration errors.
@@ -1185,14 +1165,14 @@ ifconfig_dc1="inet 10.0.0.1 netmask 255.255.255.0 media 10baseT/UTP"</programlis
<note>
<para>If a default gateway has been set in
- <filename>/etc/rc.conf</filename>, use also this
+ <filename>/etc/rc.conf</filename>, also issue this
command:</para>
<screen>&prompt.root; <userinput>service routing restart</userinput></screen>
</note>
<para>Once the networking system has been relaunched, test the
- network interfaces.</para>
+ <acronym>NIC</acronym>s.</para>
<sect3>
<title>Testing the Ethernet Card</title>
@@ -1203,8 +1183,8 @@ ifconfig_dc1="inet 10.0.0.1 netmask 255.255.255.0 media 10baseT/UTP"</programlis
</indexterm>
<para>To verify that an Ethernet card is configured correctly,
- ping the interface itself, and then ping another machine on
- the LAN:</para>
+ &man.ping.8; the interface itself, and then &man.ping.8;
+ another machine on the <acronym>LAN</acronym>:</para>
<screen>&prompt.user; <userinput>ping -c5 192.168.1.3</userinput>
PING 192.168.1.3 (192.168.1.3): 56 data bytes
@@ -1230,9 +1210,9 @@ PING 192.168.1.2 (192.168.1.2): 56 data bytes
5 packets transmitted, 5 packets received, 0% packet loss
round-trip min/avg/max/stddev = 0.700/0.729/0.766/0.025 ms</screen>
- <para>To test network resolution, use the machine name instead
- of <hostid role="ipaddr">192.168.1.2</hostid>. If there is
- no DNS server on the network,
+ <para>To test network resolution, use the host name instead
+ of the <acronym>IP</acronym> address. If there is no
+ <acronym>DNS</acronym> server on the network,
<filename>/etc/hosts</filename> must first be
configured.</para>
</sect3>
@@ -1245,20 +1225,19 @@ round-trip min/avg/max/stddev = 0.700/0.729/0.766/0.025 ms</screen>
<secondary>troubleshooting</secondary>
</indexterm>
- <para>Troubleshooting hardware and software configurations is
- always a pain, and a pain which can be alleviated by
- checking the simple things first. Is the network cable
- plugged in? Are the network services properly configured?
- Is the firewall configured correctly? Is the network card
- supported by &os;? Always before sending a bug report,
- check the hardware notes, update the version of &os; to the
- latest STABLE version, check the mailing list archives, and
- search the Internet.</para>
-
- <para>If the card works, yet performance is poor, it would be
- worthwhile to read over the &man.tuning.7; manual page.
- Also, check the network configuration as incorrect network
- settings can cause slow connections.</para>
+ <para>When troubleshooting hardware and software
+ configurations, check the simple things first. Is the
+ network cable plugged in? Are the network services properly
+ configured? Is the firewall configured correctly? Is the
+ <acronym>NIC</acronym> supported by &os;? Before sending
+ a bug report, always check the Hardware Notes, update the
+ version of &os; to the latest STABLE version, check the
+ mailing list archives, and search the Internet.</para>
+
+ <para>If the card works, yet performance is poor, read
+ through &man.tuning.7;. Also, check the network
+ configuration as incorrect network settings can cause slow
+ connections.</para>
<para>Some users experience one or two
<errorname>device timeout</errorname> messages, which is
@@ -1267,37 +1246,37 @@ round-trip min/avg/max/stddev = 0.700/0.729/0.766/0.025 ms</screen>
Double check the cable connections. Consider trying another
card.</para>
- <para>At times, users see a few
- <errorname>watchdog timeout</errorname> errors. The first
- thing to do is to check the network cable. Many cards
- require a PCI slot which supports Bus Mastering. On some
- old motherboards, only one PCI slot allows it (usually slot
- 0). Check the network card and the motherboard
+ <para>To resolve <errorname>watchdog timeout</errorname>
+ errors, first check the network cable. Many cards
+ require a <acronym>PCI</acronym> slot which supports bus
+ mastering. On some old motherboards, only one
+ <acronym>PCI</acronym> slot allows it, usually slot 0.
+ Check the <acronym>NIC</acronym> and the motherboard
documentation to determine if that may be the
problem.</para>
<para><errorname>No route to host</errorname> messages occur
if the system is unable to route a packet to the destination
- host. This can happen if no default route is specified, or
+ host. This can happen if no default route is specified or
if a cable is unplugged. Check the output of
<command>netstat -rn</command> and make sure there is a
- valid route to the host. If there is not, read on to
- <xref linkend="advanced-networking"/>.</para>
+ valid route to the host. If there is not, read <xref
+ linkend="advanced-networking"/>.</para>
<para><errorname>ping: sendto: Permission denied</errorname>
error messages are often caused by a misconfigured firewall.
- If <command>ipfw</command> is enabled in the kernel but no
- rules have been defined, then the default policy is to deny
- all traffic, even ping requests! Read on to
- <xref linkend="firewalls"/> for more information.</para>
+ If a firewall is enabled on &os; but no rules have been
+ defined, the default policy is to deny all traffic, even
+ &man.ping.8;. Refer to <xref
+ linkend="firewalls"/> for more information.</para>
- <para>Sometimes performance of the card is poor, or below
- average. In these cases it is best to set the media
+ <para>Sometimes performance of the card is poor or below
+ average. In these cases, try setting the media
selection mode from <literal>autoselect</literal> to the
- correct media selection. While this usually works for most
- hardware, it may not resolve this issue for everyone.
- Again, check all the network settings, and read over the
- &man.tuning.7; manual page.</para>
+ correct media selection. While this works for most
+ hardware, it may or may not resolve the issue. Again,
+ check all the network settings, and refer to
+ &man.tuning.7;.</para>
</sect3>
</sect2>
</sect1>
@@ -1306,9 +1285,10 @@ round-trip min/avg/max/stddev = 0.700/0.729/0.766/0.025 ms</screen>
<title>Virtual Hosts</title>
<indexterm><primary>virtual hosts</primary></indexterm>
- <indexterm><primary>IP aliases</primary></indexterm>
+ <indexterm><primary><acronym>IP</acronym>
+ aliases</primary></indexterm>
- <para>A very common use of &os; is virtual site hosting, where one
+ <para>A common use of &os; is virtual site hosting, where one
server appears to the network as many servers. This is achieved
by assigning multiple network addresses to a single
interface.</para>
@@ -1316,49 +1296,47 @@ round-trip min/avg/max/stddev = 0.700/0.729/0.766/0.025 ms</screen>
<para>A given network interface has one <quote>real</quote>
address, and may have any number of <quote>alias</quote>
addresses. These aliases are normally added by placing alias
- entries in <filename>/etc/rc.conf</filename>.</para>
-
- <para>An alias entry for the interface
- <devicename>fxp0</devicename> looks like:</para>
+ entries in <filename>/etc/rc.conf</filename>, as seen in this
+ example:</para>
<programlisting>ifconfig_fxp0_alias0="inet xxx.xxx.xxx.xxx netmask xxx.xxx.xxx.xxx"</programlisting>
- <para>Note that alias entries must start with
- <literal>alias0</literal> and proceed upwards in order, (for
- example, <literal>_alias1</literal>, <literal>_alias2</literal>,
- and so on). The configuration process will stop at the first
+ <para>Alias entries must start with
+ <literal>alias<replaceable>0</replaceable></literal> using a
+ sequential number such as
+ <literal>alias0</literal>, <literal>alias1</literal>,
+ and so on. The configuration process will stop at the first
missing number.</para>
- <para>The calculation of alias netmasks is important, but
- fortunately quite simple. For a given interface, there must be
- one address which correctly represents the network's netmask.
- Any other addresses which fall within this network must have a
- netmask of all <literal>1</literal>s (expressed as either
- <hostid role="netmask">255.255.255.255</hostid> or
- <hostid role="netmask">0xffffffff</hostid>).</para>
+ <para>The calculation of alias netmasks is important. For a
+ given interface, there must be one address which correctly
+ represents the network's netmask. Any other addresses which
+ fall within this network must have a netmask of all
+ <literal>1</literal>s, expressed as either <hostid
+ role="netmask">255.255.255.255</hostid> or <hostid
+ role="netmask">0xffffffff</hostid>.</para>
<para>For example, consider the case where the
<devicename>fxp0</devicename> interface is connected to two
- networks: the <hostid role="ipaddr">10.1.1.0</hostid> network
- with a netmask of <hostid role="netmask">255.255.255.0</hostid>
- and the <hostid role="ipaddr">202.0.75.16</hostid> network with
- a netmask of <hostid role="netmask">255.255.255.240</hostid>.
- The system is to be configured to appear in the
- range
- <hostid role="ipaddr">10.1.1.1</hostid> through
- <hostid role="ipaddr">10.1.1.5</hostid> and
- <hostid role="ipaddr">202.0.75.17</hostid> through
- <hostid role="ipaddr">202.0.75.20</hostid>. Only the first
- address in a given network range should have a real
- netmask. All the rest (<hostid role="ipaddr">10.1.1.2</hostid>
- through <hostid role="ipaddr">10.1.1.5</hostid> and
- <hostid role="ipaddr">202.0.75.18</hostid> through
- <hostid role="ipaddr">202.0.75.20</hostid>) must be configured
- with a netmask of
- <hostid role="netmask">255.255.255.255</hostid>.</para>
+ networks: <hostid role="ipaddr">10.1.1.0</hostid> with a
+ netmask of <hostid role="netmask">255.255.255.0</hostid> and
+ <hostid role="ipaddr">202.0.75.16</hostid> with a netmask of
+ <hostid role="netmask">255.255.255.240</hostid>. The system
+ is to be configured to appear in the ranges <hostid
+ role="ipaddr">10.1.1.1</hostid> through <hostid
+ role="ipaddr">10.1.1.5</hostid> and <hostid
+ role="ipaddr">202.0.75.17</hostid> through <hostid
+ role="ipaddr">202.0.75.20</hostid>. Only the first address
+ in a given network range should have a real netmask. All the
+ rest (<hostid role="ipaddr">10.1.1.2</hostid> through <hostid
+ role="ipaddr">10.1.1.5</hostid> and <hostid
+ role="ipaddr">202.0.75.18</hostid> through <hostid
+ role="ipaddr">202.0.75.20</hostid>) must be configured with
+ a netmask of <hostid
+ role="netmask">255.255.255.255</hostid>.</para>
<para>The following <filename>/etc/rc.conf</filename> entries
- configure the adapter correctly for this arrangement:</para>
+ configure the adapter correctly for this scenario:</para>
<programlisting>ifconfig_fxp0="inet 10.1.1.1 netmask 255.255.255.0"
ifconfig_fxp0_alias0="inet 10.1.1.2 netmask 255.255.255.255"
@@ -1384,31 +1362,30 @@ ifconfig_fxp0_alias7="inet 202.0.75.20 netmask 255.255.255.255"</programlisting>
</sect1info>
<title>Configuring the System Logger,
- <application>syslogd</application></title>
+ <command>syslogd</command></title>
<indexterm><primary>system logging</primary></indexterm>
<indexterm><primary>syslog</primary></indexterm>
- <indexterm><primary>syslogd</primary></indexterm>
+ <indexterm><primary>&man.syslogd.8;</primary></indexterm>
<para>System logging is an important aspect of system
- administration. It is used both to detect hardware and software
- issues and errors in the system. It also plays a very
- important role in security auditing and incident response.
- System daemons without a controlling terminal also usually log
- information to a system logging facility or other log
- file.</para>
+ administration. It is used to detect hardware and software
+ issues and errors in the system. It plays an important role
+ in security auditing and incident response. System daemons
+ without a controlling terminal usually log information to a
+ system logging facility or other log file.</para>
<para>This section describes how to configure and use the &os;
system logger, &man.syslogd.8;, and how to perform log rotation
- and log management using &man.newsyslog.8;. Focus
- will be on setting up and using <command>syslogd</command> on
- a local machine. For more advanced setups using a separate
- loghost, see <xref linkend="network-syslogd"/>.</para>
+ and log management using &man.newsyslog.8;. Focus will be on
+ setting up and using &man.syslogd.8; on a local machine. For
+ more advanced setups using a separate loghost, see <xref
+ linkend="network-syslogd"/>.</para>
<sect2>
- <title>Using <application>syslogd</application></title>
+ <title>Using <command>syslogd</command></title>
- <para>In the default &os; configuration &man.syslogd.8; is
+ <para>In the default &os; configuration, &man.syslogd.8; is
started at boot. This is controlled by the variable
<literal>syslogd_enable</literal> in
<filename>/etc/rc.conf</filename>. There are numerous
@@ -1424,7 +1401,7 @@ ifconfig_fxp0_alias7="inet 202.0.75.20 netmask 255.255.255.255"</programlisting>
</sect2>
<sect2>
- <title>Configuring <application>syslogd</application></title>
+ <title>Configuring <command>syslogd</command></title>
<indexterm><primary>syslog.conf</primary></indexterm>
@@ -1441,24 +1418,23 @@ ifconfig_fxp0_alias7="inet 202.0.75.20 netmask 255.255.255.255"</programlisting>
different log files, or discard it, depending on the facility
and level. It is also possible to take action depending on
the application that sent the message, and in the case of
- remote logging, also the hostname of the machine generating
+ remote logging, the hostname of the machine generating
the logging event.</para>
- <para>Configuring &man.syslogd.8; is quite straight
- forward. The configuration file contains one line per action,
- and the syntax for each line is a selector field followed by
- an action field. The syntax of the selector field is
- <replaceable>facility.level</replaceable> which will match
- log messages from <replaceable>facility</replaceable> at level
- <replaceable>level</replaceable> or higher. It is also
- possible to add an optional comparison flag before the level
- to specify more precisely what is logged. Multiple
+ <para>The configuration file for &man.syslogd.8; contains one
+ line per action, and the syntax for each line is a selector
+ field followed by an action field. The syntax of the selector
+ field is <replaceable>facility.level</replaceable> which will
+ match log messages from <replaceable>facility</replaceable>
+ at level <replaceable>level</replaceable> or higher. It is
+ also possible to add an optional comparison flag before the
+ level to specify more precisely what is logged. Multiple
selector fields can be used for the same action, and are
separated with a semicolon (<literal>;</literal>). Using
- <literal>*</literal> will match everything.
- The action field denotes where to send the log message,
- such as a file or a remote log host. As an example, here is
- the default <filename>syslog.conf</filename> from &os;:</para>
+ <literal>*</literal> will match everything. The action field
+ denotes where to send the log message, such as to a file or
+ remote log host. As an example, here is the default
+ <filename>syslog.conf</filename> from &os;:</para>
<programlisting># &dollar;&os;&dollar;
#
@@ -1466,7 +1442,7 @@ ifconfig_fxp0_alias7="inet 202.0.75.20 netmask 255.255.255.255"</programlisting>
# other *nix-like systems still insist on using tabs as field
# separators. If you are sharing this file between systems, you
# may want to use only tabs as field separators here.
-# Consult the &man.syslog.conf.5; manpage.
+# Consult the syslog.conf(5) manpage.
*.err;kern.warning;auth.notice;mail.crit /dev/console <co id="co-syslog-many-match"/>
*.notice;authpriv.none;kern.debug;lpr.info;mail.crit;news.err /var/log/messages
security.* /var/log/security
@@ -1499,7 +1475,8 @@ cron.* /var/log/cron
<literal>kern.warning</literal>,
<literal>auth.notice</literal> and
<literal>mail.crit</literal>, and send these log messages
- to the console (<filename>/dev/console</filename>).</para>
+ to the console
+ (<devicename>/dev/console</devicename>).</para>
</callout>
<callout arearefs="co-syslog-one-match">
@@ -1517,12 +1494,12 @@ cron.* /var/log/cron
</callout>
<callout arearefs="co-syslog-prog-spec">
- <para>Here is an example usage of a
- <emphasis>program specification</emphasis>. This will
- make the rules following only be valid for the program
- in the program specification. In this case
- this line and the following makes all messages from
- <command>ppp</command>, but no other programs, end up in
+ <para>Here is an example usage of a <emphasis>program
+ specification</emphasis>. This makes the rules
+ following it only valid for the program in the program
+ specification. In this case, this and the following
+ lines log all messages from &man.ppp.8;, but no other
+ programs, to
<filename>/var/log/ppp.log</filename>.</para>
</callout>
</calloutlist>
@@ -1532,7 +1509,7 @@ cron.* /var/log/cron
critical: <literal>emerg</literal>, <literal>alert</literal>,
<literal>crit</literal>, <literal>err</literal>,
<literal>warning</literal>, <literal>notice</literal>,
- <literal>info</literal> and <literal>debug</literal>.</para>
+ <literal>info</literal>, and <literal>debug</literal>.</para>
<para>The facilities are, in no particular order:
<literal>auth</literal>, <literal>authpriv</literal>,
@@ -1542,11 +1519,11 @@ cron.* /var/log/cron
<literal>mail</literal>, <literal>mark</literal>,
<literal>news</literal>, <literal>security</literal>,
<literal>syslog</literal>, <literal>user</literal>,
- <literal>uucp</literal> and <literal>local0</literal> through
+ <literal>uucp</literal>, and <literal>local0</literal> through
<literal>local7</literal>. Be aware that other operating
systems might have different facilities.</para>
- <para>With this knowledge it is easy to add a new line to
+ <para>With this knowledge, it is easy to add a new line to
<filename>/etc/syslog.conf</filename> to log everything from
the different daemons on level <literal>notice</literal> and
higher to <filename>/var/log/daemon.log</filename>. Just add
@@ -1556,15 +1533,15 @@ cron.* /var/log/cron
<para>For more information about the different levels and
facilities, refer to &man.syslog.3; and &man.syslogd.8;.
- For more information about <filename>syslog.conf</filename>,
- its syntax, and more advanced usage examples, see
- &man.syslog.conf.5; and
- <xref linkend="network-syslogd"/>.</para>
+ For more information about
+ <filename>/etc/syslog.conf</filename>, its syntax, and more
+ advanced usage examples, see &man.syslog.conf.5; and <xref
+ linkend="network-syslogd"/>.</para>
</sect2>
<sect2>
<title>Log Management and Rotation with
- <application>newsyslog</application></title>
+ <command>newsyslog</command></title>
<indexterm><primary>newsyslog</primary></indexterm>
<indexterm><primary>newsyslog.conf</primary></indexterm>
@@ -1578,17 +1555,17 @@ cron.* /var/log/cron
to manage log files. This program periodically rotates and
compresses log files, and optionally creates missing log files
and signals programs when log files are moved. The log files
- are not necessarily generated by syslog as &man.newsyslog.8;
- works with any logs written from any program. Note that
- <command>newsyslog</command> is normally run from
- &man.cron.8; and is not a system daemon. In the default
+ are not necessarily generated by &man.syslogd.8; as
+ &man.newsyslog.8; works with any logs written from any
+ program. While &man.newsyslog.8; is normally run from
+ &man.cron.8;, it is not a system daemon. In the default
configuration, it is run every hour.</para>
<sect3>
<title>Configuring
- <application>newsyslog</application></title>
+ <command>newsyslog</command></title>
- <para>To know what actions to take, &man.newsyslog.8; reads
+ <para>To know which actions to take, &man.newsyslog.8; reads
its configuration file, by default
<filename>/etc/newsyslog.conf</filename>. This
configuration file contains one line for each file that
@@ -1599,7 +1576,7 @@ cron.* /var/log/cron
configuration in &os;:</para>
<programlisting># configuration file for newsyslog
-# &dollar;&os;&dollar;
+# $FreeBSD$
#
# Entries which do not specify the '/pid_file' field will cause the
# syslogd process to be signalled when that log file is rotated. This
@@ -1624,7 +1601,6 @@ cron.* /var/log/cron
/var/log/cron 600 3 100 * JC
/var/log/daily.log 640 7 * @T00 JN
/var/log/debug.log 600 7 100 * JC
-/var/log/init.log 644 3 100 * J
/var/log/kerberos.log 600 7 100 * J
/var/log/lpd-errs 644 7 100 * JC
/var/log/maillog 640 7 * @T00 JC
@@ -1639,30 +1615,29 @@ cron.* /var/log/cron
/var/log/xferlog 600 7 100 * JC</programlisting>
<para>Each line starts with the name of the file to be
- rotated, optionally followed by an owner
- and group for both rotated and newly created files.
- The next field, <literal>mode</literal> is the mode of the
- files and <literal>count</literal> denotes how many rotated
- log files should be kept. The <literal>size</literal> and
- <literal>when</literal> fields tell
- <command>newsyslog</command> when to rotate the file.
- A log file is rotated when either its size is larger than
- the <literal>size</literal> field, or when the time in the
+ rotated, optionally followed by an owner and group for both
+ rotated and newly created files. The
+ <literal>mode</literal> field sets the permissions on the
+ log file and <literal>count</literal> denotes how many
+ rotated log files should be kept. The
+ <literal>size</literal> and <literal>when</literal> fields
+ tell &man.newsyslog.8; when to rotate the file. A log
+ file is rotated when either its size is larger than the
+ <literal>size</literal> field, or when the time in the
<literal>when</literal> filed has passed.
<literal>*</literal> means that this field is ignored. The
<replaceable>flags</replaceable> field gives
- &man.newsyslog.8; further instructions, such as
- how to compress the rotated file, or to create the log file
- if it is missing. The last two fields are optional, and
+ &man.newsyslog.8; further instructions, such as how to
+ compress the rotated file or to create the log file if it
+ is missing. The last two fields are optional, and
specify the <acronym
- role="Process Identifier">PID</acronym>-file of a
- process and a signal number to send to that process with
- when the file is rotated. For more information on all
- fields, valid flags and how to specify the rotation time,
- refer to &man.newsyslog.conf.5;. Remember that
- <command>newsyslog</command> is run from
- <command>cron</command> and can not rotate files more
- often than it is run from &man.cron.8;.</para>
+ role="Process Identifier">PID</acronym> file of a process
+ and a signal number to send to that process when the file
+ is rotated. For more information on all fields, valid
+ flags, and how to specify the rotation time, refer to
+ &man.newsyslog.conf.5;. Since &man.newsyslog.8; is run
+ from &man.cron.8;, it can not rotate files more often than
+ it is run from &man.cron.8;.</para>
</sect3>
</sect2>
</sect1>
@@ -1686,8 +1661,8 @@ cron.* /var/log/cron
<row>
<entry><filename
class="directory">/etc</filename></entry>
- <entry>Generic system configuration information; data
- here is system-specific.</entry>
+ <entry>Generic system-specific configuration
+ information.</entry>
</row>
<row>
@@ -1700,8 +1675,8 @@ cron.* /var/log/cron
<row>
<entry><filename
class="directory">/etc/mail</filename></entry>
- <entry>Extra &man.sendmail.8; configuration, other
- MTA configuration files.</entry>
+ <entry>Extra &man.sendmail.8; configuration and other
+ <acronym>MTA</acronym> configuration files.</entry>
</row>
<row>
@@ -1729,7 +1704,7 @@ cron.* /var/log/cron
<row>
<entry><filename
class="directory">/usr/local/etc/rc.d</filename></entry>
- <entry>Start/stop scripts for installed
+ <entry>&man.rc.8; scripts for installed
applications.</entry>
</row>
@@ -1737,8 +1712,8 @@ cron.* /var/log/cron
<entry><filename
class="directory">/var/db</filename></entry>
<entry>Automatically generated system-specific database
- files, such as the package database, the locate
- database, and so on</entry>
+ files, such as the package database and the
+ &man.locate.1; database.</entry>
</row>
</tbody>
</tgroup>
@@ -1758,12 +1733,13 @@ cron.* /var/log/cron
<primary><filename>resolv.conf</filename></primary>
</indexterm>
- <para><filename>/etc/resolv.conf</filename> dictates how
- &os;'s resolver accesses the Internet Domain Name System
- (DNS).</para>
+ <para>How a
+ &os; system accesses the Internet Domain Name System
+ (<acronym>DNS</acronym>) is controlled by
+ &man.resolv.conf.5;.</para>
<para>The most common entries to
- <filename>resolv.conf</filename> are:</para>
+ <filename>/etc/resolv.conf</filename> are:</para>
<informaltable frame="none" pgwide="1">
<tgroup cols="2">
@@ -1773,9 +1749,10 @@ cron.* /var/log/cron
<tbody>
<row>
<entry><literal>nameserver</literal></entry>
- <entry>The IP address of a name server the resolver
- should query. The servers are queried in the order
- listed with a maximum of three.</entry>
+ <entry>The <acronym>IP</acronym> address of a name
+ server the resolver should query. The servers are
+ queried in the order listed with a maximum of
+ three.</entry>
</row>
<row>
@@ -1793,7 +1770,8 @@ cron.* /var/log/cron
</tgroup>
</informaltable>
- <para>A typical <filename>resolv.conf</filename>:</para>
+ <para>A typical <filename>/etc/resolv.conf</filename> looks
+ like this:</para>
<programlisting>search example.com
nameserver 147.11.1.11
@@ -1804,9 +1782,10 @@ nameserver 147.11.100.30</programlisting>
<literal>domain</literal> options should be used.</para>
</note>
- <para>When using DHCP, &man.dhclient.8; usually rewrites
- <filename>resolv.conf</filename> with information received
- from the DHCP server.</para>
+ <para>When using <acronym>DHCP</acronym>, &man.dhclient.8;
+ usually rewrites <filename>/etc/resolv.conf</filename>
+ with information received from the <acronym>DHCP</acronym>
+ server.</para>
</sect3>
<sect3>
@@ -1815,14 +1794,17 @@ nameserver 147.11.100.30</programlisting>
<indexterm><primary>hosts</primary></indexterm>
<para><filename>/etc/hosts</filename> is a simple text
- database reminiscent of the old Internet. It works in
- conjunction with DNS and NIS providing name to IP address
- mappings. Local computers connected via a LAN can be placed
- in here for simplistic naming purposes instead of setting up
- a &man.named.8; server. Additionally,
+ database which works in conjunction with
+ <acronym>DNS</acronym> and
+ <acronym>NIS</acronym> to provide host name to
+ <acronym>IP</acronym> address mappings. Entries for local
+ computers connected via a <acronym>LAN</acronym> can be
+ added to this file for simplistic naming purposes instead
+ of setting up a &man.named.8; server. Additionally,
<filename>/etc/hosts</filename> can be used to provide a
local record of Internet names, reducing the need to query
- externally for commonly accessed names.</para>
+ external <acronym>DNS</acronym> servers for commonly
+ accessed names.</para>
<programlisting># &dollar;&os;&dollar;
#
@@ -1857,8 +1839,8 @@ nameserver 147.11.100.30</programlisting>
# from your regional registry (ARIN, APNIC, LACNIC, RIPE NCC, or AfriNIC.)
#</programlisting>
- <para><filename>/etc/hosts</filename> takes on the simple
- format of:</para>
+ <para>The format of <filename>/etc/hosts</filename> is as
+ follows:</para>
<programlisting>[Internet address] [official hostname] [alias1] [alias2] ...</programlisting>
@@ -1869,32 +1851,6 @@ nameserver 147.11.100.30</programlisting>
<para>Consult &man.hosts.5; for more information.</para>
</sect3>
</sect2>
-
- <sect2 id="configtuning-sysctlconf">
- <title><filename>sysctl.conf</filename></title>
-
- <indexterm><primary>sysctl.conf</primary></indexterm>
- <indexterm><primary>sysctl</primary></indexterm>
-
- <para><filename>sysctl.conf</filename> looks much like
- <filename>rc.conf</filename>. Values are set in a
- <literal>variable=value</literal> form. The specified values
- are set after the system goes into multi-user mode. Not all
- variables are settable in this mode.</para>
-
- <para>To turn off logging of fatal signal exits and prevent
- users from seeing processes started from other users, the
- following tunables can be set in
- <filename>sysctl.conf</filename>:</para>
-
- <programlisting># Do not log fatal signal exits (e.g., sig 11)
-kern.logsigexit=0
-
-# Prevent users from seeing information about processes that
-# are being run under another UID.
-security.bsd.see_other_uids=0</programlisting>
-
- </sect2>
</sect1>
<sect1 id="configtuning-sysctl">
@@ -1907,11 +1863,11 @@ security.bsd.see_other_uids=0</programlisting>
</indexterm>
<para>&man.sysctl.8; is used to make changes to a running &os;
- system. This includes many advanced options of the TCP/IP stack
- and virtual memory system that can dramatically improve
- performance for an experienced system administrator. Over five
- hundred system variables can be read and set using
- &man.sysctl.8;.</para>
+ system. This includes many advanced options of the
+ <acronym>TCP/IP</acronym> stack and virtual memory system
+ that can dramatically improve performance for an experienced
+ system administrator. Over five hundred system variables can
+ be read and set using &man.sysctl.8;.</para>
<para>At its core, &man.sysctl.8; serves two functions: to read
and to modify system settings.</para>
@@ -1920,13 +1876,12 @@ security.bsd.see_other_uids=0</programlisting>
<screen>&prompt.user; <userinput>sysctl -a</userinput></screen>
- <para>To read a particular variable, for example,
- <varname>kern.maxproc</varname>:</para>
+ <para>To read a particular variable, specify its name:</para>
<screen>&prompt.user; <userinput>sysctl kern.maxproc</userinput>
kern.maxproc: 1044</screen>
- <para>To set a particular variable, use the intuitive
+ <para>To set a particular variable, use the
<replaceable>variable</replaceable>=<replaceable>value</replaceable>
syntax:</para>
@@ -1934,14 +1889,41 @@ kern.maxproc: 1044</screen>
kern.maxfiles: 2088 -&gt; 5000</screen>
<para>Settings of sysctl variables are usually either strings,
- numbers, or booleans (a boolean being <literal>1</literal> for
- yes or a <literal>0</literal> for no).</para>
+ numbers, or booleans, where a a boolean is <literal>1</literal>
+ for yes or <literal>0</literal> for no.</para>
<para>To automatically set some variables each time the machine
boots, add them to <filename>/etc/sysctl.conf</filename>. For
- more information refer to &man.sysctl.conf.5; and <xref
+ more information, refer to &man.sysctl.conf.5; and <xref
linkend="configtuning-sysctlconf"/>.</para>
+ <sect2 id="configtuning-sysctlconf">
+ <title><filename>sysctl.conf</filename></title>
+
+ <indexterm><primary>sysctl.conf</primary></indexterm>
+ <indexterm><primary>sysctl</primary></indexterm>
+
+ <para>The configuration file for &man.sysctl.8;,
+ <filename>/etc/sysctl.conf</filename>, looks much like
+ <filename>/etc/rc.conf</filename>. Values are set in a
+ <literal>variable=value</literal> form. The specified values
+ are set after the system goes into multi-user mode. Not all
+ variables are settable in this mode.</para>
+
+ <para>For example, to turn off logging of fatal signal exits
+ and prevent users from seeing processes started by other
+ users, the following tunables can be set in
+ <filename>/etc/sysctl.conf</filename>:</para>
+
+ <programlisting># Do not log fatal signal exits (e.g., sig 11)
+kern.logsigexit=0
+
+# Prevent users from seeing information about processes that
+# are being run under another UID.
+security.bsd.see_other_uids=0</programlisting>
+
+ </sect2>
+
<sect2 id="sysctl-readonly">
<sect2info>
<authorgroup>
@@ -1956,34 +1938,40 @@ kern.maxfiles: 2088 -&gt; 5000</screen>
<title>&man.sysctl.8; Read-only</title>
<para>In some cases it may be desirable to modify read-only
- &man.sysctl.8; values. While this is sometimes unavoidable,
- it can only be done on (re)boot.</para>
+ &man.sysctl.8; values, which will require a reboot of the
+ system.</para>
- <para>For instance on some laptop models the &man.cardbus.4;
- device will not probe memory ranges, and fail with errors
- which look similar to:</para>
+ <para>For instance, on some laptop models the &man.cardbus.4;
+ device will not probe memory ranges and will fail with errors
+ similar to:</para>
<screen>cbb0: Could not map register memory
device_probe_and_attach: cbb0 attach returned 12</screen>
- <para>Cases like the one above usually require the modification
- of some default &man.sysctl.8; settings which are set read
- only. To overcome these situations a user can put
- &man.sysctl.8; <quote>OIDs</quote> in their local
- <filename>/boot/loader.conf</filename>. Default settings are
- located in
- <filename>/boot/defaults/loader.conf</filename>.</para>
-
- <para>Fixing the problem mentioned above would require a user to
- set <option>hw.pci.allow_unsupported_io_range=1</option> in
- the aforementioned file. Now &man.cardbus.4; will work
- properly.</para>
+ <para>The fix requires the modification of a read-only
+ &man.sysctl.8; setting. Add
+ <option>hw.pci.allow_unsupported_io_range=1</option> to
+ <filename>/boot/loader.conf</filename> and reboot. Now
+ &man.cardbus.4; should work properly.</para>
</sect2>
</sect1>
<sect1 id="configtuning-disk">
<title>Tuning Disks</title>
+ <para>The following section will discuss various tuning
+ mechanisms and options which may be applied to disk
+ devices. In many cases, disks with mechanical parts,
+ such as <acronym>SCSI</acronym> drives, will be the
+ bottleneck driving down the overall system performance. While
+ a solution is to install a drive without mechanical parts,
+ such as a solid state drive, mechanical drives are not
+ going away anytime in the near future. When tuning disks,
+ it is advisable to utilize the features of the &man.iostat.8;
+ command to test various changes to the system. This
+ command will allow the user to obtain valuable information
+ on system <acronym>IO</acronym>.</para>
+
<sect2>
<title>Sysctl Variables</title>
@@ -1994,26 +1982,29 @@ device_probe_and_attach: cbb0 attach returned 12</screen>
<primary><varname>vfs.vmiodirenable</varname></primary>
</indexterm>
- <para>The <varname>vfs.vmiodirenable</varname> sysctl variable
- may be set to either 0 (off) or 1 (on); it is 1 by default.
- This variable controls how directories are cached by the
- system. Most directories are small, using just a single
- fragment (typically 1&nbsp;K) in the file system and less
- (typically 512&nbsp;bytes) in the buffer cache. With this
- variable turned off (to 0), the buffer cache will only cache
- a fixed number of directories even if the system has a huge
- amount of memory. When turned on (to 1), this sysctl allows
- the buffer cache to use the VM Page Cache to cache the
- directories, making all the memory available for caching
- directories. However, the minimum in-core memory used to
- cache a directory is the physical page size (typically
- 4&nbsp;K) rather than 512&nbsp; bytes. Keeping this option
- enabled is recommended if the system is running any services
- which manipulate large numbers of files. Such services can
+ <para>The <varname>vfs.vmiodirenable</varname> &man.sysctl.8;
+ variable
+ may be set to either <literal>0</literal> (off) or
+ <literal>1</literal> (on). It is set to
+ <literal>1</literal> by default. This variable controls
+ how directories are cached by the system. Most directories
+ are small, using just a single fragment (typically 1&nbsp;K)
+ in the file system and typically 512&nbsp;bytes in the
+ buffer cache. With this variable turned off, the buffer
+ cache will only cache a fixed number of directories, even
+ if the system has a huge amount of memory. When turned on,
+ this &man.sysctl.8; allows the buffer cache to use the
+ <acronym>VM</acronym> page cache to cache the directories,
+ making all the memory available for caching directories.
+ However, the minimum in-core memory used to cache a
+ directory is the physical page size (typically 4&nbsp;K)
+ rather than 512&nbsp; bytes. Keeping this option enabled
+ is recommended if the system is running any services which
+ manipulate large numbers of files. Such services can
include web caches, large mail systems, and news systems.
- Keeping this option on will generally not reduce performance
- even with the wasted memory but you should experiment to
- find out.</para>
+ Keeping this option on will generally not reduce
+ performance, even with the wasted memory, but one should
+ experiment to find out.</para>
</sect3>
<sect3>
@@ -2023,14 +2014,15 @@ device_probe_and_attach: cbb0 attach returned 12</screen>
<primary><varname>vfs.write_behind</varname></primary>
</indexterm>
- <para>The <varname>vfs.write_behind</varname> sysctl variable
+ <para>The <varname>vfs.write_behind</varname> &man.sysctl.8;
+ variable
defaults to <literal>1</literal> (on). This tells the file
system to issue media writes as full clusters are collected,
which typically occurs when writing large sequential files.
- The idea is to avoid saturating the buffer cache with dirty
- buffers when it would not benefit I/O performance. However,
- this may stall processes and under certain circumstances
- should be turned off.</para>
+ This avoids saturating the buffer cache with dirty buffers
+ when it would not benefit I/O performance. However, this
+ may stall processes and under certain circumstances should
+ be turned off.</para>
</sect3>
<sect3>
@@ -2040,21 +2032,22 @@ device_probe_and_attach: cbb0 attach returned 12</screen>
<primary><varname>vfs.hirunningspace</varname></primary>
</indexterm>
- <para>The <varname>vfs.hirunningspace</varname> sysctl
+ <para>The <varname>vfs.hirunningspace</varname> &man.sysctl.8;
variable determines how much outstanding write I/O may be
queued to disk controllers system-wide at any given
- instance. The default is usually sufficient but on machines
- with lots of disks, try bumping it up to four or five
- <emphasis>megabytes</emphasis>. Note that setting too
- high a value (exceeding the buffer cache's write threshold)
- can lead to extremely bad clustering performance. Do not
- set this value arbitrarily high! Higher write values may
- add latency to reads occurring at the same time.</para>
-
- <para>There are various other buffer-cache and VM page cache
- related sysctls. Modifying these values is not recommended
- as the VM system does an extremely good job of automatically
- tuning itself.</para>
+ instance. The default is usually sufficient, but on
+ machines with many disks, try bumping it up to four or five
+ <emphasis>megabytes</emphasis>. Setting too high a value
+ which exceeds the buffer cache's write threshold can lead
+ to bad clustering performance. Do not set this value
+ arbitrarily high as higher write values may add latency to
+ reads occurring at the same time.</para>
+
+ <para>There are various other buffer cache and
+ <acronym>VM</acronym> page cache related &man.sysctl.8;
+ values. Modifying these values is not recommended as the
+ <acronym>VM</acronym> system does a good job of
+ automatically tuning itself.</para>
</sect3>
<sect3>
@@ -2064,13 +2057,13 @@ device_probe_and_attach: cbb0 attach returned 12</screen>
<primary><varname>vm.swap_idle_enabled</varname></primary>
</indexterm>
- <para>The <varname>vm.swap_idle_enabled</varname> sysctl
- variable is useful in large multi-user systems with lots of
- users entering and leaving the system and lots of idle
- processes. Such systems tend to generate a great deal of
- continuous pressure on free memory reserves. Turning this
- feature on and tweaking the swapout hysteresis (in idle
- seconds) via <varname>vm.swap_idle_threshold1</varname> and
+ <para>The <varname>vm.swap_idle_enabled</varname>
+ &man.sysctl.8; variable is useful in large multi-user
+ systems with many active login users and lots of idle
+ processes. Such systems tend to generate continuous
+ pressure on free memory reserves. Turning this feature on
+ and tweaking the swapout hysteresis (in idle seconds) via
+ <varname>vm.swap_idle_threshold1</varname> and
<varname>vm.swap_idle_threshold2</varname> depresses the
priority of memory pages associated with idle processes more
quickly then the normal pageout algorithm. This gives a
@@ -2079,8 +2072,9 @@ device_probe_and_attach: cbb0 attach returned 12</screen>
memory sooner rather than later which eats more swap and
disk bandwidth. In a small system this option will have a
determinable effect, but in a large system that is already
- doing moderate paging this option allows the VM system to
- stage whole processes into and out of memory easily.</para>
+ doing moderate paging, this option allows the
+ <acronym>VM</acronym> system to stage whole processes into
+ and out of memory easily.</para>
</sect3>
<sect3>
@@ -2090,24 +2084,23 @@ device_probe_and_attach: cbb0 attach returned 12</screen>
<primary><varname>hw.ata.wc</varname></primary>
</indexterm>
- <para>&os;&nbsp;4.3 flirted with turning off IDE write
- caching. This reduced write bandwidth to IDE disks but was
- considered necessary due to serious data consistency issues
- introduced by hard drive vendors. The problem is that IDE
- drives lie about when a write completes. With IDE write
- caching turned on, IDE hard drives not only write data to
- disk out of order, but will sometimes delay writing some
- blocks indefinitely when under heavy disk loads. A crash or
+ <para>Turning off <acronym>IDE</acronym> write caching reduces
+ write bandwidth to <acronym>IDE</acronym> disks, but may
+ sometimes be necessary due to data consistency issues
+ introduced by hard drive vendors. The problem is that
+ some <acronym>IDE</acronym> drives lie about when a write
+ completes. With <acronym>IDE</acronym> write caching
+ turned on, <acronym>IDE</acronym> hard drives write data
+ to disk out of order and will sometimes delay writing some
+ blocks indefinitely when under heavy disk load. A crash or
power failure may cause serious file system corruption.
- &os;'s default was changed to be safe. Unfortunately, the
- result was such a huge performance loss that we changed
- write caching back to on by default after the release.
Check the default on the system by observing the
- <varname>hw.ata.wc</varname> sysctl variable. If IDE write
- caching is turned off, setting this variable back to 1 will
- turn it back on. This must be done from the boot loader at
- boot time as attempting to do it after the kernel boots
- will have no effect.</para>
+ <varname>hw.ata.wc</varname> &man.sysctl.8; variable. If
+ <acronym>IDE</acronym> write caching is turned off, one can
+ set this read-only variable to
+ <literal>1</literal> in
+ <filename>/boot/loader.conf</filename> in order to enable
+ it at boot time.</para>
<para>For more information, refer to &man.ata.4;.</para>
</sect3>
@@ -2122,17 +2115,18 @@ device_probe_and_attach: cbb0 attach returned 12</screen>
<indexterm>
<primary>kernel options</primary>
- <secondary><literal>SCSI_DELAY</literal></secondary>
+ <secondary><literal>SCSI DELAY</literal></secondary>
</indexterm>
- <para>The <literal>SCSI_DELAY</literal> kernel config may be
- used to reduce system boot times. The defaults are fairly
- high and can be responsible for <literal>15</literal>
- seconds of delay in the boot process. Reducing it to
- <literal>5</literal> seconds usually works (especially with
- modern drives). The <varname>kern.cam.scsi_delay</varname>
- boot time tunable should be used. The tunable, and kernel
- config option accept values in terms of
+ <para>The <literal>SCSI_DELAY</literal> kernel configuration
+ option may be used to reduce system boot times. The
+ defaults are fairly high and can be responsible for
+ <literal>15</literal> seconds of delay in the boot process.
+ Reducing it to <literal>5</literal> seconds usually works
+ with modern drives. The
+ <varname>kern.cam.scsi_delay</varname> boot time tunable
+ should be used. The tunable and kernel configuration
+ option accept values in terms of
<emphasis>milliseconds</emphasis> and
<emphasis>not</emphasis>
<emphasis>seconds</emphasis>.</para>
@@ -2143,33 +2137,31 @@ device_probe_and_attach: cbb0 attach returned 12</screen>
<title>Soft Updates</title>
<indexterm><primary>Soft Updates</primary></indexterm>
- <indexterm><primary>tunefs</primary></indexterm>
+ <indexterm><primary>&man.tunefs.8;</primary></indexterm>
- <para>The &man.tunefs.8; program can be used to fine-tune a
- file system. This program has many different options, but for
- now we are only concerned with toggling Soft Updates on and
- off, which is done by:</para>
+ <para>To fine-tune a file system, use &man.tunefs.8;. This
+ program has many different options. To toggle Soft Updates
+ on and off, use:</para>
<screen>&prompt.root; <userinput>tunefs -n enable /filesystem</userinput>
&prompt.root; <userinput>tunefs -n disable /filesystem</userinput></screen>
- <para>A filesystem cannot be modified with &man.tunefs.8; while
+ <para>A file system cannot be modified with &man.tunefs.8; while
it is mounted. A good time to enable Soft Updates is before
any partitions have been mounted, in single-user mode.</para>
- <para>Soft Updates drastically improves meta-data performance,
+ <para>Soft Updates is recommended for <acronym>UFS</acronym>
+ file systems as it drastically improves meta-data performance,
mainly file creation and deletion, through the use of a memory
- cache. We recommend to use Soft Updates on all of your file
- systems. There are two downsides to Soft Updates that you
- should be aware of: First, Soft Updates guarantees filesystem
- consistency in the case of a crash but could very easily be
- several seconds (even a minute!) behind updating the physical
- disk. If your system crashes you may lose more work than
- otherwise. Secondly, Soft Updates delays the freeing of
- filesystem blocks. If you have a filesystem (such as the root
- filesystem) which is almost full, performing a major update,
+ cache. There are two downsides to Soft Updates to be aware
+ of. First, Soft Updates guarantee file system consistency
+ in the case of a crash, but could easily be several seconds
+ or even a minute behind updating the physical disk. If the
+ system crashes, unwritten data may be lost. Secondly, Soft
+ Updates delay the freeing of file system blocks. If the
+ root file system is almost full, performing a major update,
such as <command>make installworld</command>, can cause the
- filesystem to run out of space and the update to fail.</para>
+ file system to run out of space and the update to fail.</para>
<sect3>
<title>More Details About Soft Updates</title>
@@ -2179,142 +2171,134 @@ device_probe_and_attach: cbb0 attach returned 12</screen>
<secondary>details</secondary>
</indexterm>
- <para>There are two traditional approaches to writing a file
- systems meta-data back to disk. (Meta-data updates are
- updates to non-content data like inodes or
- directories.)</para>
+ <para>Meta-data updates are updates to non-content data like
+ inodes or directories. There are two traditional approaches
+ to writing a file system's meta-data back to disk.</para>
<para>Historically, the default behavior was to write out
- meta-data updates synchronously. If a directory had been
- changed, the system waited until the change was actually
- written to disk. The file data buffers (file contents) were
- passed through the buffer cache and backed up to disk later
- on asynchronously. The advantage of this implementation is
+ meta-data updates synchronously. If a directory changed,
+ the system waited until the change was actually written to
+ disk. The file data buffers (file contents) were passed
+ through the buffer cache and backed up to disk later on
+ asynchronously. The advantage of this implementation is
that it operates safely. If there is a failure during an
- update, the meta-data are always in a consistent state. A
+ update, meta-data is always in a consistent state. A
file is either created completely or not at all. If the
data blocks of a file did not find their way out of the
buffer cache onto the disk by the time of the crash,
- &man.fsck.8; is able to recognize this and repair the
- filesystem by setting the file length to 0. Additionally,
- the implementation is clear and simple. The disadvantage is
- that meta-data changes are slow. An
- <command>rm -r</command>, for instance, touches all the
- files in a directory sequentially, but each directory change
- (deletion of a file) will be written synchronously to the
- disk. This includes updates to the directory itself, to the
- inode table, and possibly to indirect blocks allocated by
- the file. Similar considerations apply for unrolling large
- hierarchies (<command>tar -x</command>).</para>
-
- <para>The second case is asynchronous meta-data updates. This
- is the default for Linux/ext2fs and
- <command>mount -o async</command> for *BSD ufs. All
- meta-data updates are simply being passed through the buffer
- cache too, that is, they will be intermixed with the updates
- of the file content data. The advantage of this
+ &man.fsck.8; recognizes this and repairs the file system
+ by setting the file length to
+ <literal>0</literal>. Additionally, the implementation is
+ clear and simple. The disadvantage is that meta-data
+ changes are slow. For example, <command>rm -r</command>
+ touches all the files in a directory sequentially, but each
+ directory change will be written synchronously to the
+ disk. This includes updates to the directory itself, to
+ the inode table, and possibly to indirect blocks allocated
+ by the file. Similar considerations apply for unrolling
+ large hierarchies using <command>tar -x</command>.</para>
+
+ <para>The second approach is to use asynchronous meta-data
+ updates. This is the default for a <acronym>UFS</acronym>
+ file system mounted with <command>mount -o async</command>.
+ Since all meta-data updates are also passed through the
+ buffer cache, they will be intermixed with the updates of
+ the file content data. The advantage of this
implementation is there is no need to wait until each
meta-data update has been written to disk, so all operations
which cause huge amounts of meta-data updates work much
- faster than in the synchronous case. Also, the
- implementation is still clear and simple, so there is a low
- risk for bugs creeping into the code. The disadvantage is
- that there is no guarantee at all for a consistent state of
- the filesystem. If there is a failure during an operation
- that updated large amounts of meta-data (like a power
- failure, or someone pressing the reset button), the
- filesystem will be left in an unpredictable state. There is
- no opportunity to examine the state of the filesystem when
- the system comes up again; the data blocks of a file could
- already have been written to the disk while the updates of
- the inode table or the associated directory were not. It is
- actually impossible to implement a <command>fsck</command>
- which is able to clean up the resulting chaos (because the
- necessary information is not available on the disk). If the
- filesystem has been damaged beyond repair, the only choice
- is to use &man.newfs.8; on it and restore it from
- backup.</para>
-
- <para>The usual solution for this problem was to implement
+ faster than in the synchronous case. This implementation
+ is still clear and simple, so there is a low risk for bugs
+ creeping into the code. The disadvantage is that there is
+ no guarantee for a consistent state of the file system.
+ If there is a failure during an operation that updated
+ large amounts of meta-data, like a power failure or someone
+ pressing the reset button, the file system will be left
+ in an unpredictable state. There is no opportunity to
+ examine the state of the file system when the system comes
+ up again as the data blocks of a file could already have
+ been written to the disk while the updates of the inode
+ table or the associated directory were not. It is
+ impossible to implement a &man.fsck.8; which is able to
+ clean up the resulting chaos because the necessary
+ information is not available on the disk. If the file
+ system has been damaged beyond repair, the only choice
+ is to reformat it and restore from backup.</para>
+
+ <para>The usual solution for this problem is to implement
<emphasis>dirty region logging</emphasis>, which is also
- referred to as <emphasis>journaling</emphasis>, although
- that term is not used consistently and is occasionally
- applied to other forms of transaction logging as well.
+ referred to as <emphasis>journaling</emphasis>.
Meta-data updates are still written synchronously, but only
- into a small region of the disk. Later on they will be
- moved to their proper location. Because the logging area is
- a small, contiguous region on the disk, there are no long
+ into a small region of the disk. Later on, they are moved
+ to their proper location. Because the logging area is a
+ small, contiguous region on the disk, there are no long
distances for the disk heads to move, even during heavy
operations, so these operations are quicker than synchronous
- updates. Additionally the complexity of the implementation
- is fairly limited, so the risk of bugs being present is low.
- A disadvantage is that all meta-data are written twice (once
- into the logging region and once to the proper location) so
- for normal work, a performance <quote>pessimization</quote>
- might result. On the other hand, in case of a crash, all
- pending meta-data operations can be quickly either
- rolled-back or completed from the logging area after the
- system comes up again, resulting in a fast filesystem
- startup.</para>
-
- <para>Kirk McKusick, the developer of Berkeley FFS, solved
- this problem with Soft Updates: all pending meta-data
- updates are kept in memory and written out to disk in a
- sorted sequence (<quote>ordered meta-data updates</quote>).
- This has the effect that, in case of heavy meta-data
- operations, later updates to an item <quote>catch</quote>
- the earlier ones if the earlier ones are still in memory and
- have not already been written to disk. So all operations
- on, say, a directory are generally performed in memory
- before the update is written to disk (the data blocks are
+ updates. Additionally, the complexity of the implementation
+ is limited, so the risk of bugs being present is low. A
+ disadvantage is that all meta-data is written twice, once
+ into the logging region and once to the proper location, so
+ performance <quote>pessimization</quote> might result. On
+ the other hand, in case of a crash, all pending meta-data
+ operations can be either quickly rolled back or completed
+ from the logging area after the system comes up again,
+ resulting in a fast file system startup.</para>
+
+ <para>Kirk McKusick, the developer of Berkeley
+ <acronym>FFS</acronym>, solved this problem with Soft
+ Updates. All pending meta-data updates are kept in memory
+ and written out to disk in a sorted sequence
+ (<quote>ordered meta-data updates</quote>). This has the
+ effect that, in case of heavy meta-data operations, later
+ updates to an item <quote>catch</quote> the earlier ones
+ which are still in memory and have not already been written
+ to disk. All operations are generally performed in memory
+ before the update is written to disk and the data blocks are
sorted according to their position so that they will not be
- on the disk ahead of their meta-data). If the system
- crashes, this causes an implicit <quote>log rewind</quote>:
- all operations which did not find their way to the disk
- appear as if they had never happened. A consistent
- filesystem state is maintained that appears to be the one of
- 30 to 60 seconds earlier. The algorithm used guarantees
- that all resources in use are marked as such in their
- appropriate bitmaps: blocks and inodes. After a crash, the
- only resource allocation error that occurs is that resources
- are marked as <quote>used</quote> which are actually
- <quote>free</quote>. &man.fsck.8; recognizes this situation,
- and frees the resources that are no longer used. It is safe
- to ignore the dirty state of the filesystem after a crash by
- forcibly mounting it with <command>mount -f</command>. In
- order to free resources that may be unused, &man.fsck.8;
- needs to be run at a later time. This is the idea behind
- the <emphasis>background fsck</emphasis>: at system startup
- time, only a <emphasis>snapshot</emphasis> of the filesystem
- is recorded. The <command>fsck</command> can be run later
- on. All file systems can then be mounted
+ on the disk ahead of their meta-data. If the system
+ crashes, an implicit <quote>log rewind</quote> causes all
+ operations which were not written to the disk appear as if
+ they never happened. A consistent file system state is
+ maintained that appears to be the one of 30 to 60 seconds
+ earlier. The algorithm used guarantees that all resources
+ in use are marked as such in their blocks and inodes.
+ After a crash, the only resource allocation error that
+ occurs is that resources are marked as <quote>used</quote>
+ which are actually <quote>free</quote>. &man.fsck.8;
+ recognizes this situation, and frees the resources that
+ are no longer used. It is safe to ignore the dirty state
+ of the file system after a crash by forcibly mounting it
+ with <command>mount -f</command>. In order to free
+ resources that may be unused, &man.fsck.8; needs to be run
+ at a later time. This is the idea behind the
+ <emphasis>background &man.fsck.8;</emphasis>: at system
+ startup time, only a <emphasis>snapshot</emphasis> of the
+ file system is recorded and &man.fsck.8; is run afterwards.
+ All file systems can then be mounted
<quote>dirty</quote>, so the system startup proceeds in
- multiuser mode. Then, background <command>fsck</command>s
- will be scheduled for all file systems where this is
- required, to free resources that may be unused. (File
- systems that do not use Soft Updates still need the usual
- foreground <command>fsck</command> though.)</para>
+ multi-user mode. Then, background &man.fsck.8; is
+ scheduled for all file systems where this is required, to
+ free resources that may be unused. File systems that do
+ not use Soft Updates still need the usual foreground
+ &man.fsck.8;.</para>
<para>The advantage is that meta-data operations are nearly
- as fast as asynchronous updates which are, faster than
+ as fast as asynchronous updates and are faster than
<emphasis>logging</emphasis>, which has to write the
meta-data twice. The disadvantages are the complexity of
- the code (implying a higher risk for bugs in an area that is
- highly sensitive regarding loss of user data), and a higher
- memory consumption. Additionally there are some
- idiosyncrasies one has to get used to. After a crash, the
- state of the filesystem appears to be somewhat
- <quote>older</quote>. In situations where the standard
- synchronous approach would have caused some zero-length
- files to remain after the <command>fsck</command>, these
- files do not exist at all with a Soft Updates filesystem
- because neither the meta-data nor the file contents have
- ever been written to disk. Disk space is not released until
+ the code, a higher memory consumption, and some
+ idiosyncrasies. After a crash, the state of the file
+ system appears to be somewhat <quote>older</quote>. In
+ situations where the standard synchronous approach would
+ have caused some zero-length files to remain after the
+ &man.fsck.8;, these files do not exist at all with Soft
+ Updates because neither the meta-data nor the file contents
+ have been written to disk. Disk space is not released until
the updates have been written to disk, which may take place
- some time after running <command>rm</command>. This may
- cause problems when installing large amounts of data on a
- filesystem that does not have enough free space to hold all
- the files twice.</para>
+ some time after running &man.rm.1;. This may cause problems
+ when installing large amounts of data on a file system
+ that does not have enough free space to hold all the files
+ twice.</para>
</sect3>
</sect2>
</sect1>
@@ -2337,13 +2321,13 @@ device_probe_and_attach: cbb0 attach returned 12</screen>
<primary><varname>kern.maxfiles</varname></primary>
</indexterm>
- <para><varname>kern.maxfiles</varname> can be raised or
- lowered based upon system requirements. This variable
- indicates the maximum number of file descriptors on the
- system. When the file descriptor table is full,
- <errorname>file: table is full</errorname> will show up
- repeatedly in the system message buffer, which can be viewed
- using <command>dmesg</command>.</para>
+ <para>The <varname>kern.maxfiles</varname> &man.sysctl.8;
+ variable can be raised or lowered based upon system
+ requirements. This variable indicates the maximum number
+ of file descriptors on the system. When the file descriptor
+ table is full, <errorname>file: table is full</errorname>
+ will show up repeatedly in the system message buffer, which
+ can be viewed using &man.dmesg.8;.</para>
<para>Each open file, socket, or fifo uses one file
descriptor. A large-scale production server may easily
@@ -2362,18 +2346,20 @@ device_probe_and_attach: cbb0 attach returned 12</screen>
resources needed may be similar to a high-scale web
server.</para>
- <para>The variable <varname>kern.maxusers</varname> is
- automatically sized at boot based on the amount of memory
- available in the system, and may be determined at run-time
- by inspecting the value of the read-only
- <varname>kern.maxusers</varname> sysctl. Some sites will
- require larger or smaller values of
- <varname>kern.maxusers</varname> and may set it as a loader
- tunable; values of 64, 128, and 256 are not uncommon. Going
- above 256 is not recommended unless a huge number of file
- descriptors are needed. Many of the tunable values set to
- their defaults by <varname>kern.maxusers</varname> may be
- individually overridden at boot-time or run-time in
+ <para>The read-only &man.sysctl.8; variable
+ <varname>kern.maxusers</varname> is automatically sized at
+ boot based on the amount of memory available in the system,
+ and may be determined at run-time by inspecting the value
+ of <varname>kern.maxusers</varname>. Some systems require
+ larger or smaller values of
+ <varname>kern.maxusers</varname> and values of
+ <literal>64</literal>, <literal>128</literal>, and
+ <literal>256</literal> are not uncommon. Going above
+ <literal>256</literal> is not recommended unless a huge
+ number of file descriptors is needed. Many of the tunable
+ values set to their defaults by
+ <varname>kern.maxusers</varname> may be individually
+ overridden at boot-time or run-time in
<filename>/boot/loader.conf</filename>. Refer to
&man.loader.conf.5; and
<filename>/boot/defaults/loader.conf</filename> for more
@@ -2381,37 +2367,39 @@ device_probe_and_attach: cbb0 attach returned 12</screen>
<para>In older releases, the system will auto-tune
<literal>maxusers</literal> if it is set to
- <literal>0</literal>
+ <literal>0</literal>.
<footnote><para>The auto-tuning algorithm sets
<literal>maxusers</literal> equal to the amount of
- memory in the system, with a minimum of 32, and a
- maximum of 384.</para></footnote>. When setting this
- option, set <literal>maxusers</literal> to at least 4,
- especially if the system runs
- <application>Xorg</application> or is used to
+ memory in the system, with a minimum of
+ <literal>32</literal>, and a maximum of
+ <literal>384</literal>.</para></footnote>. When
+ setting this option, set <literal>maxusers</literal> to
+ at least <literal>4</literal>, especially if the system
+ runs <application>&xorg;</application> or is used to
compile software. The most important table set by
<literal>maxusers</literal> is the maximum number of
processes, which is set to
<literal>20 + 16 * maxusers</literal>. If
- <literal>maxusers</literal> is set to 1, there can only be
- 36 simultaneous processes, including the 18 or so that the
- system starts up at boot time and the 15 or so used by
- <application>Xorg</application>. Even a simple task like
+ <literal>maxusers</literal> is set to <literal>1</literal>,
+ there can only be
+ <literal>36</literal> simultaneous processes, including
+ the <literal>18</literal> or so that the system starts up
+ at boot time and the <literal>15</literal> or so used by
+ <application>&xorg;</application>. Even a simple task like
reading a manual page will start up nine processes to
filter, decompress, and view it. Setting
- <literal>maxusers</literal> to 64 allows up to 1044
- simultaneous processes, which should be enough for nearly
- all uses. If, however, you see the dreaded
- <errortype>proc table full</errortype> error when trying to
- start another program, or are running a server with a large
- number of simultaneous users (like
- <hostid role="fqdn">ftp.FreeBSD.org</hostid>), increase the
- number and rebuild.</para>
+ <literal>maxusers</literal> to <literal>64</literal> allows
+ up to <literal>1044</literal> simultaneous processes, which
+ should be enough for nearly all uses. If, however, the
+ <errortype>proc table full</errortype> error is displayed
+ when trying to start another program, or a server is
+ running with a large number of simultaneous users, increase
+ the number and rebuild.</para>
<note>
<para><literal>maxusers</literal> does
<emphasis>not</emphasis> limit the number of users which
- can log into your machine. It simply sets various table
+ can log into the machine. It instead sets various table
sizes to reasonable values considering the maximum number
of users on the system and how many processes each user
will be running.</para>
@@ -2425,19 +2413,19 @@ device_probe_and_attach: cbb0 attach returned 12</screen>
<primary><varname>kern.ipc.somaxconn</varname></primary>
</indexterm>
- <para>The <varname>kern.ipc.somaxconn</varname> sysctl
+ <para>The <varname>kern.ipc.somaxconn</varname> &man.sysctl.8;
variable limits the size of the listen queue for accepting
- new TCP connections. The default value of
- <literal>128</literal> is typically too low for robust
- handling of new connections in a heavily loaded web server
- environment. For such environments, it is recommended to
- increase this value to <literal>1024</literal> or higher.
- The service daemon may itself limit the listen queue size
- (e.g., &man.sendmail.8;, or
- <application>Apache</application>) but will often have a
- directive in its configuration file to adjust the queue
- size. Large listen queues also do a better job of avoiding
- Denial of Service (<abbrev>DoS</abbrev>) attacks.</para>
+ new <literal>TCP</literal> connections. The default value
+ of <literal>128</literal> is typically too low for robust
+ handling of new connections on a heavily loaded web server.
+ For such environments, it is recommended to increase this
+ value to <literal>1024</literal> or higher. A service
+ such as &man.sendmail.8;, or
+ <application>Apache</application> may itself limit the
+ listen queue size, but will often have a directive in its
+ configuration file to adjust the queue size. Large listen
+ queues do a better job of avoiding Denial of Service
+ (<acronym>DoS</acronym>) attacks.</para>
</sect3>
</sect2>
@@ -2447,22 +2435,26 @@ device_probe_and_attach: cbb0 attach returned 12</screen>
<para>The <literal>NMBCLUSTERS</literal> kernel configuration
option dictates the amount of network Mbufs available to the
system. A heavily-trafficked server with a low number of
- Mbufs will hinder &os;'s ability. Each cluster represents
- approximately 2&nbsp;K of memory, so a value of 1024
- represents 2 megabytes of kernel memory reserved for network
- buffers. A simple calculation can be done to figure out how
- many are needed. A web server which maxes out at 1000
- simultaneous connections where each connection uses a
- 6&nbsp;K receive and 16&nbsp;K send buffer, requires
- approximately 32&nbsp;MB worth of network buffers to cover the
- web server. A good rule of thumb is to multiply by 2, so
+ Mbufs will hinder performance. Each cluster represents
+ approximately 2&nbsp;K of memory, so a value of
+ <literal>1024</literal> represents <literal>2</literal>
+ megabytes of kernel memory reserved for network buffers. A
+ simple calculation can be done to figure out how many are
+ needed. A web server which maxes out at
+ <literal>1000</literal> simultaneous connections where each
+ connection uses a 6&nbsp;K receive and 16&nbsp;K send buffer,
+ requires approximately 32&nbsp;MB worth of network buffers
+ to cover the web server. A good rule of thumb is to multiply
+ by <literal>2</literal>, so
2x32&nbsp;MB&nbsp;/&nbsp;2&nbsp;KB&nbsp;=
- 64&nbsp;MB&nbsp;/&nbsp;2&nbsp;kB&nbsp;= 32768. Values between
- 4096 and 32768 are recommended for machines with greater
- amounts of memory. Under no circumstances should you specify
- an arbitrarily high value for this parameter as it could lead
- to a boot time crash. To observe network cluster usage, use
- <option>-m</option> with &man.netstat.1;.</para>
+ 64&nbsp;MB&nbsp;/&nbsp;2&nbsp;kB&nbsp;=
+ <literal>32768</literal>. Values between
+ <literal>4096</literal> and <literal>32768</literal> are
+ recommended for machines with greater amounts of memory.
+ Never specify an arbitrarily high value for this parameter
+ as it could lead to a boot time crash. To observe network
+ cluster usage, use <option>-m</option> with
+ &man.netstat.1;.</para>
<para>The <varname>kern.ipc.nmbclusters</varname> loader tunable
should be used to tune this at boot time. Only older versions
@@ -2477,11 +2469,11 @@ device_probe_and_attach: cbb0 attach returned 12</screen>
setting its value in <filename>/boot/loader.conf</filename>
(see &man.loader.8; for details). A common indicator that
this parameter needs to be adjusted is when processes are seen
- in the <literal>sfbufa</literal> state. The sysctl variable
- <varname>kern.ipc.nsfbufs</varname> is a read-only glimpse at
- the kernel configured variable. This parameter nominally
- scales with <varname>kern.maxusers</varname>, however it may
- be necessary to tune accordingly.</para>
+ in the <literal>sfbufa</literal> state. The &man.sysctl.8;
+ variable <varname>kern.ipc.nsfbufs</varname> is read-only.
+ This parameter nominally scales with
+ <varname>kern.maxusers</varname>, however it may be necessary
+ to tune accordingly.</para>
<important>
<para>Even though a socket has been marked as non-blocking,
@@ -2498,82 +2490,90 @@ device_probe_and_attach: cbb0 attach returned 12</screen>
<primary>net.inet.ip.portrange.*</primary>
</indexterm>
- <para>The <varname>net.inet.ip.portrange.*</varname> sysctl
+ <para>The <varname>net.inet.ip.portrange.*</varname>
+ &man.sysctl.8;
variables control the port number ranges automatically bound
- to TCP and UDP sockets. There are three ranges: a low
- range, a default range, and a high range. Most network
- programs use the default range which is controlled by the
+ to <literal>TCP</literal> and <literal>UDP</literal>
+ sockets. There are three ranges: a low range, a default
+ range, and a high range. Most network programs use the
+ default range which is controlled by
<varname>net.inet.ip.portrange.first</varname> and
<varname>net.inet.ip.portrange.last</varname>, which default
- to 1024 and 5000, respectively. Bound port ranges are used
- for outgoing connections, and it is possible to run the
- system out of ports under certain circumstances. This most
- commonly occurs when running a heavily loaded web proxy.
- The port range is not an issue when running servers which
- handle mainly incoming connections, such as a normal web
- server, or has a limited number of outgoing connections,
- such as a mail relay. For situations where there is a
- shortage of ports, it is recommended to increase
+ to <literal>1024</literal> and <literal>5000</literal>,
+ respectively. Bound port ranges are used for outgoing
+ connections and it is possible to run the system out of
+ ports under certain circumstances. This most commonly
+ occurs when running a heavily loaded web proxy. The port
+ range is not an issue when running a server which handles
+ mainly incoming connections, such as a web server, or has
+ a limited number of outgoing connections, such as a mail
+ relay. For situations where there is a shortage of ports,
+ it is recommended to increase
<varname>net.inet.ip.portrange.last</varname> modestly. A
value of <literal>10000</literal>, <literal>20000</literal>
or <literal>30000</literal> may be reasonable. Consider
firewall effects when changing the port range. Some
- firewalls may block large ranges of ports (usually
- low-numbered ports) and expect systems to use higher ranges
- of ports for outgoing connections &mdash; for this reason it
- is not recommended that
+ firewalls may block large ranges of ports, usually
+ low-numbered ports, and expect systems to use higher ranges
+ of ports for outgoing connections. For this reason, it
+ is not recommended that the value of
<varname>net.inet.ip.portrange.first</varname> be
lowered.</para>
</sect3>
<sect3>
- <title>TCP Bandwidth Delay Product</title>
+ <title><literal>TCP</literal> Bandwidth Delay Product</title>
<indexterm>
- <primary>TCP Bandwidth Delay Product Limiting</primary>
+ <primary><literal>TCP</literal> Bandwidth Delay Product
+ Limiting</primary>
<secondary><varname>net.inet.tcp.inflight.enable</varname></secondary>
</indexterm>
- <para>The TCP Bandwidth Delay Product Limiting is similar to
- TCP/Vegas in NetBSD. It can be enabled by setting
- <varname>net.inet.tcp.inflight.enable</varname> sysctl
- variable to <literal>1</literal>. The system will attempt
- to calculate the bandwidth delay product for each connection
- and limit the amount of data queued to the network to just
- the amount required to maintain optimum throughput.</para>
+ <para><literal>TCP</literal> bandwidth delay product limiting
+ can be enabled by setting the
+ <varname>net.inet.tcp.inflight.enable</varname>
+ &man.sysctl.8; variable to <literal>1</literal>. This
+ instructs the system to attempt to calculate the bandwidth
+ delay product for each connection and limit the amount of
+ data queued to the network to just the amount required to
+ maintain optimum throughput.</para>
<para>This feature is useful when serving data over modems,
- Gigabit Ethernet, or even high speed WAN links (or any other
- link with a high bandwidth delay product), especially when
- also using window scaling or when a large send window has
- been configured. When enabling this option, also be sure to
- set <varname>net.inet.tcp.inflight.debug</varname> to
- <literal>0</literal> (disable debugging), and for production
- use setting <varname>net.inet.tcp.inflight.min</varname> to
- at least <literal>6144</literal> may be beneficial.
- However, note that setting high minimums may effectively
- disable bandwidth limiting depending on the link. The
- limiting feature reduces the amount of data built up in
- intermediate route and switch packet queues and reduces the
- amount of data built up in the local host's interface queue.
- With fewer queued packets, interactive connections,
- especially over slow modems, will operate with lower
+ Gigabit Ethernet, high speed <literal>WAN</literal> links,
+ or any other link with a high bandwidth delay product,
+ especially when also using window scaling or when a large
+ send window has been configured. When enabling this option,
+ also set <varname>net.inet.tcp.inflight.debug</varname> to
+ <literal>0</literal> to disable debugging. For production
+ use, setting <varname>net.inet.tcp.inflight.min</varname>
+ to at least <literal>6144</literal> may be beneficial.
+ Setting high minimums may effectively disable bandwidth
+ limiting, depending on the link. The limiting feature
+ reduces the amount of data built up in intermediate route
+ and switch packet queues and reduces the amount of data
+ built up in the local host's interface queue. With fewer
+ queued packets, interactive connections, especially over
+ slow modems, will operate with lower
<emphasis>Round Trip Times</emphasis>. This feature only
- effects server side data transmission such as uploading. It
- has no effect on data reception or downloading.</para>
+ effects server side data transmission such as uploading.
+ It has no effect on data reception or downloading.</para>
<para>Adjusting <varname>net.inet.tcp.inflight.stab</varname>
is <emphasis>not</emphasis> recommended. This parameter
- defaults to 20, representing 2 maximal packets added to the
- bandwidth delay product window calculation. The additional
- window is required to stabilize the algorithm and improve
- responsiveness to changing conditions, but it can also
- result in higher ping times over slow links, though still
- much lower than without the inflight algorithm. In such
- cases, try reducing this parameter to 15, 10, or 5; and
- reducing <varname>net.inet.tcp.inflight.min</varname> (for
- example, to 3500) to get the desired effect. Reducing these
- parameters should be done as a last resort only.</para>
+ defaults to <literal>20</literal>, representing 2 maximal
+ packets added to the bandwidth delay product window
+ calculation. The additional window is required to stabilize
+ the algorithm and improve responsiveness to changing
+ conditions, but it can also result in higher &man.ping.8;
+ times over slow links, though still much lower than without
+ the inflight algorithm. In such cases, try reducing this
+ parameter to <literal>15</literal>,
+ <literal>10</literal>, or <literal>5</literal> and
+ reducing <varname>net.inet.tcp.inflight.min</varname>
+ to a value such as <literal>3500</literal> to get the
+ desired effect. Reducing these parameters should be done
+ as a last resort only.</para>
</sect3>
</sect2>
@@ -2584,13 +2584,14 @@ device_probe_and_attach: cbb0 attach returned 12</screen>
<title><varname>kern.maxvnodes</varname></title>
<para>A vnode is the internal representation of a file or
- directory. So increasing the number of vnodes available to
- the operating system cuts down on disk I/O. Normally this
- is handled by the operating system and does not need to be
+ directory. Increasing the number of vnodes available to
+ the operating system reduces disk I/O. Normally, this is
+ handled by the operating system and does not need to be
changed. In some cases where disk I/O is a bottleneck and
- the system is running out of vnodes, this setting will need
- to be increased. The amount of inactive and free RAM will
- need to be taken into account.</para>
+ the system is running out of vnodes, this setting needs
+ to be increased. The amount of inactive and free
+ <acronym>RAM</acronym> will need to be taken into
+ account.</para>
<para>To see the current number of vnodes in use:</para>
@@ -2602,14 +2603,14 @@ vfs.numvnodes: 91349</screen>
<screen>&prompt.root; <userinput>sysctl kern.maxvnodes</userinput>
kern.maxvnodes: 100000</screen>
- <para>If the current vnode usage is near the maximum,
+ <para>If the current vnode usage is near the maximum, try
increasing <varname>kern.maxvnodes</varname> by a value of
- 1,000 is probably a good idea. Keep an eye on the number of
+ <literal>1000</literal>. Keep an eye on the number of
<varname>vfs.numvnodes</varname>. If it climbs up to the
maximum again, <varname>kern.maxvnodes</varname> will need
- to be increased further. A shift in your memory usage as
- reported by &man.top.1; should be visible. More memory
- should be active.</para>
+ to be increased further. Otherwise, a shift in memory
+ usage as reported by &man.top.1; should be visible and
+ more memory should be active.</para>
</sect3>
</sect2>
</sect1>
@@ -2617,24 +2618,23 @@ kern.maxvnodes: 100000</screen>
<sect1 id="adding-swap-space">
<title>Adding Swap Space</title>
- <para>Despite careful planning, sometimes a system does not run
- as expected. If more swap space is needed, it is simple enough
- to add. There are three ways to increase swap space: add a new
- hard drive, enable swap over NFS, or create a swap file on an
- existing partition.</para>
+ <para>Sometimes a system requires more swap space. There are
+ three ways to increase swap space: add a new hard drive,
+ enable swap over <literal>NFS</literal>, or create a swap file
+ on an existing partition.</para>
- <para>For information on how to encrypt swap space, what options
- for this task exist and why it should be done, refer to
- <xref linkend="swap-encrypting"/> of the Handbook.</para>
+ <para>For information on how to encrypt swap space, which options
+ exist, and why it should be done, refer to <xref
+ linkend="swap-encrypting"/>.</para>
<sect2 id="new-drive-swap">
<title>Swap on a New or Existing Hard Drive</title>
<para>Adding a new hard drive for swap gives better performance
than adding a partition on an existing drive. Setting up
- partitions and hard drives is explained in
- <xref linkend="disks-adding"/>.
- <xref linkend="configtuning-initial"/> discusses partition
+ partitions and hard drives is explained in <xref
+ linkend="disks-adding"/> while <xref
+ linkend="configtuning-initial"/> discusses partition
layouts and swap partition size considerations.</para>
<para>Use &man.swapon.8; to add a swap partition to the system.
@@ -2653,8 +2653,7 @@ kern.maxvnodes: 100000</screen>
</warning>
<para>To automatically add this swap partition on boot, add an
- entry to <filename>/etc/fstab</filename> for the
- partition:</para>
+ entry to <filename>/etc/fstab</filename>:</para>
<programlisting><replaceable>/dev/ada1s1b</replaceable> none swap sw 0 0</programlisting>
@@ -2663,19 +2662,20 @@ kern.maxvnodes: 100000</screen>
</sect2>
<sect2 id="nfs-swap">
- <title>Swapping over NFS</title>
+ <title>Swapping over <literal>NFS</literal></title>
- <para>Swapping over NFS is only recommended if you do not have a
- local hard disk to swap to; NFS swapping will be limited by
- the available network bandwidth and puts an additional burden
- on the NFS server.</para>
+ <para>Swapping over <literal>NFS</literal> is only recommended
+ when there is no local hard disk to swap to.
+ <literal>NFS</literal> swapping will be limited by the
+ available network bandwidth and puts an additional burden
+ on &man.nfsd.8;.</para>
</sect2>
<sect2 id="create-swapfile">
<title>Swapfiles</title>
- <para>You can create a file of a specified size to use as a swap
- file. The following example will create a 64MB file named
+ <para>To create a swap file, specify its size. The following
+ example creates a 64MB file named
<filename>/usr/swap0</filename>.</para>
<example>
@@ -2686,8 +2686,8 @@ kern.maxvnodes: 100000</screen>
<para>The <filename>GENERIC</filename> kernel already
includes the memory disk driver (&man.md.4;) required
- for this operation. When building a custom kernel, make
- sure to include the following line in the custom
+ for this operation. When building a custom kernel,
+ make sure to include the following line in the custom
configuration file:</para>
<programlisting>device md</programlisting>
@@ -2697,15 +2697,15 @@ kern.maxvnodes: 100000</screen>
</listitem>
<listitem>
- <para>Create a swapfile
- (<filename>/usr/swap0</filename>):</para>
+ <para>First, create the swapfile
+ <filename>/usr/swap0</filename>:</para>
<screen>&prompt.root; <userinput>dd if=/dev/zero of=/usr/swap0 bs=1024k count=64</userinput></screen>
</listitem>
<listitem>
- <para>Set proper permissions on
- (<filename>/usr/swap0</filename>):</para>
+ <para>Then, set proper permissions on
+ <filename>/usr/swap0</filename>:</para>
<screen>&prompt.root; <userinput>chmod 0600 /usr/swap0</userinput></screen>
</listitem>
@@ -2718,7 +2718,7 @@ kern.maxvnodes: 100000</screen>
</listitem>
<listitem>
- <para>Reboot the machine or to enable the swap file
+ <para>Reboot the machine or, to enable the swap file
immediately, type:</para>
<screen>&prompt.root; <userinput>mdconfig -a -t vnode -f /usr/swap0 -u 0 &amp;&amp; swapon /dev/md0</userinput></screen>
@@ -2753,10 +2753,9 @@ kern.maxvnodes: 100000</screen>
was managed by the <acronym>BIOS</acronym> and the user had less
control and visibility into the power management settings. Some
limited configurability was available via <emphasis>Advanced
- Power Management (APM)</emphasis>. Power and resource
- management is one of the key components of a modern operating
- system. It allows the operating system to monitor system
- limits and to possibly provide an alert if the system
+ Power Management (<acronym>APM</acronym>)</emphasis>. Power
+ and resource management allows the operating system to monitor
+ system limits and to possibly provide an alert if the system
temperature increases unexpectedly.</para>
<para>This section provides comprehensive information about
@@ -2787,83 +2786,90 @@ kern.maxvnodes: 100000</screen>
</sect2>
<sect2 id="acpi-old-spec">
- <title>Shortcomings of Advanced Power Management (APM)</title>
+ <title>Shortcomings of Advanced Power Management</title>
<para>The <acronym>APM</acronym> facility controls the power
- usage of a system based on its activity. The APM BIOS is
- supplied by the (system) vendor and is specific to the
- hardware platform. An APM driver in the operating system
- mediates access to the <emphasis>APM Software
- Interface</emphasis>, which allows management of power
- levels. APM should still be used for systems manufactured at
- or before the year 2000.</para>
-
- <para>There are four major problems in APM. Firstly, power
- management is done by the (vendor-specific) BIOS, and the OS
- does not have any knowledge of it. One example of this, is
- when the user sets idle-time values for a hard drive in the
- APM BIOS, that when exceeded, it (BIOS) would spin down the
- hard drive, without the consent of the OS. Secondly, the APM
- logic is embedded in the BIOS, and it operates outside the
- scope of the OS. This means users can only fix problems in
- their APM BIOS by flashing a new one into the ROM; which is a
- very dangerous procedure with the potential to leave the
- system in an unrecoverable state if it fails. Thirdly, APM is
- a vendor-specific technology, which means that there is a lot
- of parity (duplication of efforts) and bugs found in one
- vendor's BIOS, may not be solved in others. Last but not the
- least, the APM BIOS did not have enough room to implement a
- sophisticated power policy, or one that can adapt very well to
- the purpose of the machine.</para>
-
- <para><emphasis>Plug and Play BIOS (PNPBIOS)</emphasis> was
- unreliable in many situations. PNPBIOS is 16-bit technology,
- so the OS has to use 16-bit emulation in order to
- <quote>interface</quote> with PNPBIOS methods.</para>
+ usage of a system based on its activity. The
+ <acronym>APM</acronym> <acronym>BIOS</acronym> is supplied
+ by the vendor and is specific to the hardware platform. An
+ <acronym>APM</acronym> driver in the operating system
+ mediates access to the <emphasis><acronym>APM</acronym>
+ Software Interface</emphasis>, which allows management of
+ power levels. <acronym>APM</acronym> should still be used
+ for systems manufactured at or before the year 2000.</para>
+
+ <para>There are four major problems in <acronym>APM</acronym>.
+ First, power management is done by the vendor-specific
+ <acronym>BIOS</acronym>, separate from the operating system.
+ For example, the user can set idle-time values for a hard
+ drive in the <acronym>APM</acronym> <acronym>BIOS</acronym>
+ so that, when exceeded, the <acronym>BIOS</acronym> spins
+ down the hard drive without the consent of the operating
+ system. Second, the <acronym>APM</acronym> logic is embedded
+ in the <acronym>BIOS</acronym>, and it operates outside the
+ scope of the operating system. This means that users can
+ only fix problems in the <acronym>APM</acronym>
+ <acronym>BIOS</acronym> by flashing a new one into the
+ <acronym>ROM</acronym>, which is a dangerous procedure with
+ the potential to leave the system in an unrecoverable state
+ if it fails. Third, <acronym>APM</acronym> is a
+ vendor-specific technology, meaning that there is a lot of
+ duplication of efforts and bugs found in one vendor's
+ <acronym>BIOS</acronym> may not be solved in others. Lastly,
+ the <acronym>APM</acronym> <acronym>BIOS</acronym> did not
+ have enough room to implement a sophisticated power policy
+ or one that can adapt well to the purpose of the
+ machine.</para>
+
+ <para>The <emphasis>Plug and Play <acronym>BIOS</acronym>
+ (<acronym>PNPBIOS</acronym>)</emphasis> was unreliable in
+ many situations. <acronym>PNPBIOS</acronym> is 16-bit
+ technology, so the operating system has to use 16-bit
+ emulation in order to interface with
+ <acronym>PNPBIOS</acronym> methods.</para>
<para>The &os; <acronym>APM</acronym> driver is documented in
- the &man.apm.4; manual page.</para>
+ &man.apm.4;.</para>
</sect2>
<sect2 id="acpi-config">
<title>Configuring <acronym>ACPI</acronym></title>
- <para>The <filename>acpi.ko</filename> driver is loaded by
- default at start up by the &man.loader.8; and should
+ <para>The &man.acpi.4; driver is loaded by default at start
+ up by &man.loader.8; and should
<emphasis>not</emphasis> be compiled into the kernel. The
- reasoning behind this is that modules are easier to work with,
- say if switching to another <filename>acpi.ko</filename>
- without doing a kernel rebuild. This has the advantage of
- making testing easier. Another reason is that starting
+ reasoning is that modules are easier to work with and do not
+ require a kernel rebuild. This has the advantage of making
+ testing easier. Another reason is that starting
<acronym>ACPI</acronym> after a system has been brought up
- often does not work well. If you are experiencing problems,
+ often does not work well. If experiencing problems,
<acronym>ACPI</acronym> can be disabled altogether. This
driver should not and can not be unloaded because the system
bus uses it for various hardware interactions.
- <acronym>ACPI</acronym> can be disabled by setting
- <literal>hint.acpi.0.disabled="1"</literal> in
- <filename>/boot/loader.conf</filename> or at the
- &man.loader.8; prompt.</para>
+ <acronym>ACPI</acronym> can be disabled by rebooting after
+ setting <literal>hint.acpi.0.disabled="1"</literal> in
+ <filename>/boot/loader.conf</filename> or by setting this
+ variable at the &man.loader.8; prompt.</para>
<note>
<para><acronym>ACPI</acronym> and <acronym>APM</acronym>
cannot coexist and should be used separately. The last one
- to load will terminate if the driver notices the other
+ to load will terminate if the driver notices the other is
running.</para>
</note>
<para><acronym>ACPI</acronym> can be used to put the system into
a sleep mode with &man.acpiconf.8;, the <option>-s</option>
- flag, and a <literal>1-5</literal> option. Most users will
- only need <literal>1</literal> or <literal>3</literal>
- (suspend to RAM). Option <literal>5</literal> will do a
- soft-off which is the same action as:</para>
+ flag, and a <literal>1-5</literal> option. Most users
+ only need <literal>1</literal> (quick suspend to
+ <acronym>RAM</acronym>) or <literal>3</literal> (suspend to
+ <acronym>RAM</acronym>). Option <literal>5</literal> performs
+ a soft-off which is the same action as:</para>
<screen>&prompt.root; <userinput>halt -p</userinput></screen>
- <para>Other options are available via &man.sysctl.8;. Check out
- the &man.acpi.4; and &man.acpiconf.8; manual pages for more
- information.</para>
+ <para>Other options are available via &man.sysctl.8;. Refer to
+ &man.acpi.4; and &man.acpiconf.8; for more information.</para>
</sect2>
</sect1>
@@ -2909,16 +2915,16 @@ kern.maxvnodes: 100000</screen>
<para>This section is intended to help users assist the &os;
<acronym>ACPI</acronym> maintainers in identifying the root
- cause of problems you observe and debugging and developing a
+ cause of problems and in debugging and developing a
solution.</para>
<sect2 id="ACPI-submitdebug">
<title>Submitting Debugging Information</title>
<note>
- <para>Before submitting a problem, be sure you are running the
- latest <acronym>BIOS</acronym> version and, if available,
- embedded controller firmware version.</para>
+ <para>Before submitting a problem, ensure the latest
+ <acronym>BIOS</acronym> version is installed and, if
+ available, the embedded controller firmware version.</para>
</note>
<para>When submitting a problem, send the following information
@@ -2934,45 +2940,44 @@ kern.maxvnodes: 100000</screen>
</listitem>
<listitem>
- <para>The &man.dmesg.8; output after
+ <para>The output of &man.dmesg.8; after running
<command>boot -v</command>, including any error messages
generated by the bug.</para>
</listitem>
<listitem>
- <para>The &man.dmesg.8; output from
- <command>boot -v</command> with <acronym>ACPI</acronym>
- disabled, if disabling it helps fix the problem.</para>
+ <para>The &man.dmesg.8; output from <command>boot
+ -v</command> with <acronym>ACPI</acronym> disabled,
+ if disabling it helps to fix the problem.</para>
</listitem>
<listitem>
<para>Output from <command>sysctl hw.acpi</command>. This
- is also a good way of figuring out what features the
- system offers.</para>
+ lists which features the system offers.</para>
</listitem>
<listitem>
- <para><acronym>URL</acronym> where the
+ <para>The <acronym>URL</acronym> to a pasted version of the
<firstterm><acronym>ACPI</acronym> Source
- Language</firstterm> (<acronym>ASL</acronym>) can be
- found. Do <emphasis>not</emphasis> send the
+ Language</firstterm> (<acronym>ASL</acronym>). Do
+ <emphasis>not</emphasis> send the
<acronym>ASL</acronym> directly to the list as it can be
very large. Generate a copy of the
<acronym>ASL</acronym> by running this command:</para>
<screen>&prompt.root; <userinput>acpidump -dt &gt; <replaceable>name</replaceable>-<replaceable>system</replaceable>.asl</userinput></screen>
- <para>(Substitute your login name for
+ <para>Substitute the login name for
<replaceable>name</replaceable> and manufacturer/model for
- <replaceable>system</replaceable>. Example:
- <filename>njl-FooCo6000.asl</filename>)</para>
+ <replaceable>system</replaceable>. For example, use
+ <filename>njl-FooCo6000.asl</filename>.</para>
</listitem>
</itemizedlist>
<para>Most &os; developers watch &a.current;, but one should
- submit problems to &a.acpi.name; to be sure it is
- seen. Be patient when waiting for a response. If the bug is
- not immediately apparent, you may be asked to submit a
+ submit problems to &a.acpi.name; to be sure it is seen. Be
+ patient when waiting for a response. If the bug is not
+ immediately apparent, submit a
<acronym>PR</acronym> using &man.send-pr.1;. When entering a
<acronym>PR</acronym>, include the same information as
requested above. This helps developers to track the problem
@@ -2985,7 +2990,7 @@ kern.maxvnodes: 100000</screen>
<title>Background</title>
<indexterm>
- <primary>ACPI</primary>
+ <primary><acronym>ACPI</acronym></primary>
</indexterm>
<para><acronym>ACPI</acronym> is present in all modern computers
@@ -2995,33 +3000,32 @@ kern.maxvnodes: 100000</screen>
planes control, thermal zones, various battery systems,
embedded controllers, and bus enumeration. Most systems
implement less than the full standard. For instance, a
- desktop system usually only implements the bus enumeration
- parts while a laptop might have cooling and battery management
+ desktop system usually only implements bus enumeration
+ while a laptop might have cooling and battery management
support as well. Laptops also have suspend and resume, with
their own associated complexity.</para>
<para>An <acronym>ACPI</acronym>-compliant system has various
components. The <acronym>BIOS</acronym> and chipset vendors
- provide various fixed tables (e.g., <acronym>FADT</acronym>)
+ provide various fixed tables, such as <acronym>FADT</acronym>,
in memory that specify things like the <acronym>APIC</acronym>
map (used for <acronym>SMP</acronym>), config registers, and
- simple configuration values. Additionally, a table of
- bytecode (the <firstterm>Differentiated System Description
- Table</firstterm> <acronym>DSDT</acronym>) is provided that
- specifies a tree-like name space of devices and
- methods.</para>
+ simple configuration values. Additionally, a bytecode table,
+ the <firstterm>Differentiated System Description
+ Table</firstterm> <acronym>DSDT</acronym>, specifies a
+ tree-like name space of devices and methods.</para>
<para>The <acronym>ACPI</acronym> driver must parse the fixed
tables, implement an interpreter for the bytecode, and modify
device drivers and the kernel to accept information from the
<acronym>ACPI</acronym> subsystem. For &os;, &intel; has
provided an interpreter (<acronym>ACPI-CA</acronym>) that is
- shared with Linux and NetBSD. The path to the
+ shared with &linux; and NetBSD. The path to the
<acronym>ACPI-CA</acronym> source code is <filename
class="directory">src/sys/contrib/dev/acpica</filename>.
The glue code that allows <acronym>ACPI-CA</acronym> to work
- on &os; is in
- <filename class="directory">src/sys/dev/acpica/Osd</filename>.
+ on &os; is in <filename
+ class="directory">src/sys/dev/acpica/Osd</filename>.
Finally, drivers that implement various
<acronym>ACPI</acronym> devices are found in <filename
class="directory">src/sys/dev/acpica</filename>.</para>
@@ -3046,8 +3050,8 @@ kern.maxvnodes: 100000</screen>
<para>In some cases, resuming from a suspend operation will
cause the mouse to fail. A known work around is to add
<literal>hint.psm.0.flags="0x3000"</literal> to
- <filename>/boot/loader.conf</filename>. If this does
- not work, consider sending a bug report using
+ <filename>/boot/loader.conf</filename>. If this does not
+ work, consider sending a bug report using
&man.send-pr.1;.</para>
</sect3>
@@ -3061,9 +3065,9 @@ kern.maxvnodes: 100000</screen>
<literal>S4</literal>. <literal>S5</literal> is
<quote>soft off</quote> and is the normal state the system
is in when plugged in but not powered up.
- <literal>S4</literal> can actually be implemented two
- separate ways. <literal>S4</literal><acronym>BIOS</acronym>
- is a <acronym>BIOS</acronym>-assisted suspend to disk.
+ <literal>S4</literal> can be implemented in two separate
+ ways. <literal>S4</literal><acronym>BIOS</acronym> is a
+ <acronym>BIOS</acronym>-assisted suspend to disk.
<literal>S4</literal><acronym>OS</acronym> is implemented
entirely by the operating system.</para>
@@ -3085,13 +3089,13 @@ hw.acpi.s4bios: 0</screen>
<para>When testing suspend/resume, start with
<literal>S1</literal>, if supported. This state is most
likely to work since it does not require much driver
- support. No one has implemented <literal>S2</literal> which
- is similar to <literal>S1</literal>. The next thing to try
- is <literal>S3</literal>. This is the deepest
+ support. No one has implemented <literal>S2</literal>,
+ which is similar to <literal>S1</literal>. Next, try
+ <literal>S3</literal>. This is the deepest
<acronym>STR</acronym> state and requires a lot of driver
- support to properly reinitialize the hardware. If you have
- problems resuming, feel free to email &a.acpi.name;, but do
- not expect the problem to be resolved since there are a lot
+ support to properly reinitialize the hardware. If there are
+ problems resuming, email &a.acpi.name;. However, the
+ problem may not be resolved quickly since due to the amount
of drivers and hardware that need more testing and
work.</para>
@@ -3104,70 +3108,67 @@ hw.acpi.s4bios: 0</screen>
&prompt.root; <userinput>sysctl debug.acpi.suspend_bounce=1</userinput>
&prompt.root; <userinput>acpiconf -s 3</userinput></screen>
- <para>This test emulates suspend/resume cycle of all device
- drivers without actually going into <literal>S3</literal>
- state. In some cases, problems such as losing firmware
- state, device watchdog time out, and retrying forever, can
- be captured with this method. Note that the system will
- not really enter <literal>S3</literal> state, which means
- devices may not lose power, and many will work fine even if
- suspend/resume methods are totally missing, unlike real
- <literal>S3</literal> state.</para>
+ <para>This test emulates the suspend/resume cycle of all
+ device drivers without actually going into
+ <literal>S3</literal> state. In some cases, problems such
+ as losing firmware state, device watchdog time out, and
+ retrying forever, can be captured with this method. Note
+ that the system will not really enter <literal>S3</literal>
+ state, which means devices may not lose power, and many
+ will work fine even if suspend/resume methods are totally
+ missing, unlike real <literal>S3</literal> state.</para>
<para>Harder cases require additional hardware, such as a
- serial port/cable for serial console or a Firewire
- port/cable for &man.dcons.4;, and kernel debugging
- skills.</para>
+ serial port and cable for debugging through a serial
+ console, a Firewire port and cable for using &man.dcons.4;,
+ and kernel debugging skills.</para>
- <para>To help isolate the problem, remove as many drivers from
- the kernel as possible. If it works, narrow down which
+ <para>To help isolate the problem, remove as many drivers
+ from the kernel as possible. If it works, narrow down which
driver is the problem by loading drivers until it fails
- again. Typically binary drivers like
+ again. Typically, binary drivers like
<filename>nvidia.ko</filename>, display drivers, and
<acronym>USB</acronym> will have the most problems while
- Ethernet interfaces usually work fine. If you can properly
- load/unload the drivers, automate this by putting the
+ Ethernet interfaces usually work fine. If drivers can be
+ properly loaded and unloaded, automate this by putting the
appropriate commands in
<filename>/etc/rc.suspend</filename> and
- <filename>/etc/rc.resume</filename>. There is a
- commented-out example for unloading and loading a driver.
- Try setting <option>hw.acpi.reset_video</option> to zero
- (<literal>0</literal>) if the display is messed up after
+ <filename>/etc/rc.resume</filename>.
+ Try setting <option>hw.acpi.reset_video</option> to
+ <literal>0</literal> if the display is messed up after
resume. Try setting longer or shorter values for
<option>hw.acpi.sleep_delay</option> to see if that
helps.</para>
- <para>Another thing to try is load a recent Linux distribution
- with <acronym>ACPI</acronym> support and test their
- suspend/resume support on the same hardware. If it works on
- Linux, it is likely a &os; driver problem and narrowing down
- which driver causes the problems will help us fix the
- problem. Note that the <acronym>ACPI</acronym> maintainers
- do not usually maintain other drivers, such as sound or
- <acronym>ATA</acronym>, so any work done on tracking
- down a driver problem should probably eventually be posted
- to the &a.current.name; list and mailed to the driver
- maintainer. Advanced users can start by putting some
- debugging &man.printf.3;s in a problematic driver to track
- down where in its resume function it hangs.</para>
+ <para>Try loading a recent &linux; distribution to see if
+ suspend/resume works on the same hardware. If it works on
+ &linux;, it is likely a &os; driver problem. Narrowing down
+ which driver causes the problem will assist developers in
+ fixing the problem. Since the <acronym>ACPI</acronym>
+ maintainers rarely maintain other drivers, such as sound
+ or <acronym>ATA</acronym>, any driver problems should also
+ be posted to the &a.current.name; list and mailed to the
+ driver maintainer. Advanced users can include debugging
+ &man.printf.3;s in a problematic driver to track down where
+ in its resume function it hangs.</para>
<para>Finally, try disabling <acronym>ACPI</acronym> and
enabling <acronym>APM</acronym> instead. If suspend/resume
- works with <acronym>APM</acronym>, you may be better off
- sticking with <acronym>APM</acronym>, especially on older
- hardware (pre-2000). It took vendors a while to get
+ works with <acronym>APM</acronym>, stick with
+ <acronym>APM</acronym>, especially on older hardware
+ (pre-2000). It took vendors a while to get
<acronym>ACPI</acronym> support correct and older hardware
is more likely to have <acronym>BIOS</acronym> problems with
<acronym>ACPI</acronym>.</para>
</sect3>
<sect3>
- <title>System Hangs (Temporary or Permanent)</title>
+ <title>System Hangs</title>
<para>Most system hangs are a result of lost interrupts or an
- interrupt storm. Chipsets have a lot of problems based on
+ interrupt storm. Chipsets may have problems based on boot,
how the <acronym>BIOS</acronym> configures interrupts before
- boot, correctness of the <acronym>APIC</acronym>
+ correctness of the <acronym>APIC</acronym>
(<acronym>MADT</acronym>) table, and routing of the
<firstterm>System Control Interrupt</firstterm>
(<acronym>SCI</acronym>).</para>
@@ -3178,7 +3179,6 @@ hw.acpi.s4bios: 0</screen>
<para>Interrupt storms can be distinguished from lost
interrupts by checking the output of
-
<command>vmstat -i</command> and looking at the line that
has <literal>acpi0</literal>. If the counter is increasing
at more than a couple per second, there is an interrupt
@@ -3195,10 +3195,10 @@ hw.acpi.s4bios: 0</screen>
<secondary>disabling</secondary>
</indexterm>
- <para>When dealing with interrupt problems try disabling
+ <para>When dealing with interrupt problems, try disabling
<acronym>APIC</acronym> support with
<literal>hint.apic.0.disabled="1"</literal> in
- <filename>loader.conf</filename>.</para>
+ <filename>/boot/loader.conf</filename>.</para>
</sect3>
<sect3>
@@ -3206,14 +3206,14 @@ hw.acpi.s4bios: 0</screen>
<para>Panics are relatively rare for <acronym>ACPI</acronym>
and are the top priority to be fixed. The first step is to
- isolate the steps to reproduce the panic (if possible) and
+ isolate the steps to reproduce the panic, if possible, and
get a backtrace. Follow the advice for enabling
<literal>options DDB</literal> and setting up a serial
- console (see <xref linkend="serialconsole-ddb"/>) or setting
+ console in <xref linkend="serialconsole-ddb"/> or setting
up a &man.dump.8; partition. To get a backtrace in
<acronym>DDB</acronym>, use <literal>tr</literal>. When
- handwriting the backtrace, get at least the lowest five (5)
- and top five (5) lines in the trace.</para>
+ handwriting the backtrace, get at least the last five
+ and the top five lines in the trace.</para>
<para>Then, try to isolate the problem by booting with
<acronym>ACPI</acronym> disabled. If that works, isolate
@@ -3226,8 +3226,8 @@ hw.acpi.s4bios: 0</screen>
<title>System Powers Up After Suspend or Shutdown</title>
<para>First, try setting
- <literal>hw.acpi.disable_on_poweroff="0"</literal>
- in &man.loader.conf.5;. This keeps <acronym>ACPI</acronym>
+ <literal>hw.acpi.disable_on_poweroff="0"</literal> in
+ &man.loader.conf.5;. This keeps <acronym>ACPI</acronym>
from disabling various events during the shutdown process.
Some systems need this value set to <literal>1</literal>
(the default) for the same reason. This usually fixes the
@@ -3238,9 +3238,9 @@ hw.acpi.s4bios: 0</screen>
<sect3>
<title>Other Problems</title>
- <para>For other problems with <acronym>ACPI</acronym> such as
+ <para>For other problems with <acronym>ACPI</acronym>, such as
it not working with a docking station or devices not being
- detected, email a description to the mailing list. Some
+ detected, email a description to &a.acpi.name;. Some
issues may be related to unfinished parts of the
<acronym>ACPI</acronym> subsystem which might take a while
to be implemented. Be patient and prepared to test
@@ -3249,38 +3249,35 @@ hw.acpi.s4bios: 0</screen>
</sect2>
<sect2 id="ACPI-aslanddump">
- <title><acronym>ASL</acronym>, <command>acpidump</command>, and
+ <title><acronym>ASL</acronym>, &man.acpidump.8;, and
<acronym>IASL</acronym></title>
<indexterm>
- <primary>ACPI</primary>
- <secondary>ASL</secondary>
+ <primary><acronym>ACPI</acronym></primary>
+ <secondary><acronym>ASL</acronym></secondary>
</indexterm>
- <para>The most common problem is the <acronym>BIOS</acronym>
- vendors providing incorrect (or outright buggy!) bytecode.
- This is usually manifested by kernel console messages like
- this:</para>
+ <para>Some <acronym>BIOS</acronym> vendors provide incorrect
+ or buggy bytecode. This is usually manifested by kernel
+ console messages like this:</para>
<screen>ACPI-1287: *** Error: Method execution failed [\\_SB_.PCI0.LPC0.FIGD._STA] \\
(Node 0xc3f6d160), AE_NOT_FOUND</screen>
<para>Often, these problems may be resolved by updating the
<acronym>BIOS</acronym> to the latest revision. Most console
- messages are harmless but if when there are other problems
- like the battery status is not working, these messages are a
- good place to start looking for problems in the
- <acronym>AML</acronym>. The bytecode, known as
- <acronym>AML</acronym>, is compiled from a source language
- called <acronym>ASL</acronym>. The <acronym>AML</acronym> is
- found in the table known as the <acronym>DSDT</acronym>. To
- get a copy of the system's <acronym>ASL</acronym>, use
- &man.acpidump.8;. Include both <option>-t</option>, to
- show the contents of the fixed tables, and
- <option>-d</option>, to disassemble the
- <acronym>AML</acronym>. Refer to <link
- linkend="ACPI-submitdebug">Submitting Debugging
- Information</link> for an example syntax.</para>
+ messages are harmless, but if there are other problems like
+ the battery status is not working, these messages are a
+ good place to start looking for problems. The bytecode,
+ known as <acronym>AML</acronym>, is compiled from a source
+ language called <acronym>ASL</acronym>. The
+ <acronym>AML</acronym> is found in the table known as the
+ <acronym>DSDT</acronym>. To get a copy of the system's
+ <acronym>ASL</acronym>, use &man.acpidump.8;. Include both
+ <option>-t</option>, to show the contents of the fixed tables,
+ and <option>-d</option>, to disassemble the
+ <acronym>AML</acronym>. Refer to <xref
+ linkend="ACPI-submitdebug"/> for an example syntax.</para>
<para>The simplest first check is to recompile the
<acronym>ASL</acronym> to check for errors. Warnings can
@@ -3293,36 +3290,34 @@ hw.acpi.s4bios: 0</screen>
</sect2>
<sect2 id="ACPI-fixasl">
- <title>Fixing Your <acronym>ASL</acronym></title>
+ <title>Fixing the <acronym>ASL</acronym></title>
<indexterm>
- <primary>ACPI</primary>
- <secondary>ASL</secondary>
+ <primary><acronym>ACPI</acronym></primary>
+ <secondary><acronym>ASL</acronym></secondary>
</indexterm>
- <para>In the long run, the goal of &os; is for almost everyone
- to have working <acronym>ACPI</acronym> without any user
- intervention. At this point, workarounds are still being
- developed for common mistakes made by the
- <acronym>BIOS</acronym> vendors. The &microsoft; interpreter
- (<filename>acpi.sys</filename> and
+ <para>The goal of &os; is for everyone to have working
+ <acronym>ACPI</acronym> without any user intervention. At
+ this point, workarounds are still being developed for common
+ mistakes made by <acronym>BIOS</acronym> vendors. The
+ &microsoft; interpreter (<filename>acpi.sys</filename> and
<filename>acpiec.sys</filename>) does not strictly check for
adherence to the standard, and thus many
<acronym>BIOS</acronym> vendors who only test
<acronym>ACPI</acronym> under &windows; never fix their
<acronym>ASL</acronym>. &os; developers continue to identify
- and document exactly what non-standard behavior is allowed by
- &microsoft;'s interpreter and replicate it so &os; can work
- without forcing users to fix the <acronym>ASL</acronym>. As a
- workaround, and to help identify behavior, fix the
+ and document which non-standard behavior is allowed by
+ &microsoft;'s interpreter and replicate it so that &os; can
+ work without forcing users to fix the <acronym>ASL</acronym>.
+ As a workaround, and to help identify behavior, fix the
<acronym>ASL</acronym> manually. If this works, send a
&man.diff.1; of the old and new <acronym>ASL</acronym> so
developers can possibly work around the buggy behavior in
- <acronym>ACPI-CA</acronym> and thus make the unnecessary
- fix.</para>
+ <acronym>ACPI-CA</acronym>.</para>
<indexterm>
- <primary>ACPI</primary>
+ <primary><acronym>ACPI</acronym></primary>
<secondary>error messages</secondary>
</indexterm>
@@ -3330,15 +3325,14 @@ hw.acpi.s4bios: 0</screen>
how to fix them:</para>
<sect3>
- <title>_OS Dependencies</title>
-
- <para>Some <acronym>AML</acronym> assumes the world consists
- of various &windows; versions. You can tell &os; to claim
- it is any <acronym>OS</acronym> to see if this fixes
- problems you may have. An easy way to override this is to
- set <literal>hw.acpi.osname="Windows 2001"</literal> in
- <filename>/boot/loader.conf</filename> or other similar
- strings you find in the <acronym>ASL</acronym>.</para>
+ <title>Operating System Dependencies</title>
+
+ <para>Some <acronym>AML</acronym> versions assume the user is
+ running &windows;. To override this, set
+ <literal>hw.acpi.osname=<replaceable>"Windows
+ 2001"</replaceable></literal> in
+ <filename>/boot/loader.conf</filename>, using the strings
+ in the <acronym>ASL</acronym>.</para>
</sect3>
<sect3>
@@ -3347,9 +3341,9 @@ hw.acpi.s4bios: 0</screen>
<para>Some methods do not explicitly return a value as the
standard requires. While <acronym>ACPI-CA</acronym>
does not handle this, &os; has a workaround that allows it
- to return the value implicitly. Explicit Return statements
- can be added where required if you know what value should be
- returned. To force <command>iasl</command> to compile the
+ to return the value implicitly. Explicit return statements
+ can be added where required if the value which should be
+ returned is known. To force &man.iasl.8; to compile the
<acronym>ASL</acronym>, use the <option>-f</option>
flag.</para>
</sect3>
@@ -3362,18 +3356,17 @@ hw.acpi.s4bios: 0</screen>
<screen>&prompt.root; <userinput>iasl your.asl</userinput></screen>
- <para>Adding the <option>-f</option> flag will force creation
+ <para>Adding the <option>-f</option> flag forces creation
of the <acronym>AML</acronym>, even if there are errors
- during compilation. Some errors, such as missing Return
+ during compilation. Some errors, such as missing return
statements, are automatically worked around by the
interpreter.</para>
- <para><filename>DSDT.aml</filename> is the default output
- filename for <command>iasl</command>. Load this file
- instead of the <acronym>BIOS</acronym>'s buggy copy, which
- is still present in flash memory, by editing
- <filename>/boot/loader.conf</filename> as
- follows:</para>
+ <para>The default output filename for &man.iasl.8; is
+ <filename>DSDT.aml</filename>. Load this file instead of
+ the <acronym>BIOS</acronym>'s buggy copy, which is still
+ present in flash memory, by editing
+ <filename>/boot/loader.conf</filename> as follows:</para>
<programlisting>acpi_dsdt_load="YES"
acpi_dsdt_name="/boot/DSDT.aml"</programlisting>
@@ -3397,7 +3390,7 @@ acpi_dsdt_name="/boot/DSDT.aml"</programlisting>
<secondary>debugging</secondary>
</indexterm>
- <para>The <acronym>ACPI</acronym> driver has a very flexible
+ <para>The <acronym>ACPI</acronym> driver has a flexible
debugging facility. A set of subsystems and the level of
verbosity can be specified. The subsystems to debug are
specified as <quote>layers</quote> and are broken down into
@@ -3408,29 +3401,29 @@ acpi_dsdt_name="/boot/DSDT.aml"</programlisting>
ACPI_LV_ERROR (just report errors) to ACPI_LV_VERBOSE
(everything). The <quote>level</quote> is a bitmask so
multiple options can be set at once, separated by spaces. In
- practice, a serial console should be used to log the output if
- it is so long it flushes the console message buffer. A full
- list of the individual layers and levels is found in
+ practice, a serial console should be used to log the output
+ so it is not lost as the console message buffer flushes.
+ A full list of the individual layers and levels is found in
&man.acpi.4;.</para>
<para>Debugging output is not enabled by default. To enable it,
add <literal>options ACPI_DEBUG</literal> to the kernel
configuration file if <acronym>ACPI</acronym> is compiled into
the kernel. Add <literal>ACPI_DEBUG=1</literal> to
- <filename>/etc/make.conf</filename> to enable it
- globally. If it is a module, recompile just the
+ <filename>/etc/make.conf</filename> to enable it globally.
+ If it is a module, recompile just the
<filename>acpi.ko</filename> module as follows:</para>
<screen>&prompt.root; <userinput>cd /sys/modules/acpi/acpi
&amp;&amp; make clean &amp;&amp;
make ACPI_DEBUG=1</userinput></screen>
- <para>Install <filename>acpi.ko</filename> in
- <filename class="directory">/boot/kernel</filename> and add
- the desired level and layer to
- <filename>loader.conf</filename>. This example enables debug
- messages for all <acronym>ACPI-CA</acronym> components and all
- <acronym>ACPI</acronym> hardware drivers such as
+ <para>Install <filename>acpi.ko</filename> in <filename
+ class="directory">/boot/kernel</filename> and add the
+ desired level and layer to
+ <filename>/boot/loader.conf</filename>. This example enables
+ debug messages for all <acronym>ACPI-CA</acronym> components
+ and all <acronym>ACPI</acronym> hardware drivers such as
(<acronym>CPU</acronym> and <acronym>LID</acronym>. It only
outputs error messages at the least verbose level.</para>
@@ -3439,11 +3432,12 @@ debug.acpi.level="ACPI_LV_ERROR"</programlisting>
<para>If the required information is triggered by a specific
event, such as a suspend and then resume, leave out changes to
- <filename>loader.conf</filename> and instead use
- <command>sysctl</command> to specify the layer and level after
- booting and preparing the system for the specific event. The
- <command>sysctl</command>s are named the same as the tunables
- in <filename>loader.conf</filename>.</para>
+ <filename>/boot/loader.conf</filename> and instead use
+ &man.sysctl.8; to specify the layer and level after booting
+ and preparing the system for the specific event. The
+ variables which can be set using &man.sysctl.8; are named
+ the same as the tunables in
+ <filename>/boot/loader.conf</filename>.</para>
</sect2>
<sect2 id="ACPI-References">
@@ -3475,16 +3469,16 @@ debug.acpi.level="ACPI_LV_ERROR"</programlisting>
</listitem>
<listitem>
- <para>&os; Manual pages: &man.acpi.4;,
+ <para>&man.acpi.4;,
&man.acpi.thermal.4;, &man.acpidump.8;, &man.iasl.8;,
- &man.acpidb.8;</para>
+ and &man.acpidb.8;</para>
</listitem>
<listitem>
<para><ulink
url="http://www.cpqlinux.com/acpi-howto.html#fix_broken_dsdt">
- <acronym>DSDT</acronym> debugging resource</ulink>.
- (Uses Compaq as an example but generally useful.)</para>
+ <acronym>DSDT</acronym> debugging
+ resource</ulink>.</para>
</listitem>
</itemizedlist>
</sect2>
diff --git a/en_US.ISO8859-1/books/handbook/disks/chapter.xml b/en_US.ISO8859-1/books/handbook/disks/chapter.xml
index 182fd40c3d..b92339ed4c 100644
--- a/en_US.ISO8859-1/books/handbook/disks/chapter.xml
+++ b/en_US.ISO8859-1/books/handbook/disks/chapter.xml
@@ -3690,42 +3690,33 @@ geli_da2_flags="-p -k /root/da2.key"</programlisting>
<secondary>encrypting</secondary>
</indexterm>
- <para>Swap encryption in &os; is easy to configure. Depending on
- which version of &os; is being used, different options are
- available and configuration can vary slightly. The &man.gbde.8;
- or &man.geli.8; encryption systems can be used for swap
- encryption. Both systems use the <filename>encswap</filename>
+ <para>Like the encryption of disk partitions, encryption of swap
+ space is used to protect sensitive information. Consider an
+ application that deals with passwords. As long as these
+ passwords stay in physical memory, these passwords will not
+ be written to disk and be cleared after a reboot. If &os;
+ starts swapping out memory pages to free
+ space for other applications, the passwords may be written to
+ the disk platters unencrypted. Encrypting swap space can be a
+ solution for this scenario.</para>
+
+ <para>The &man.gbde.8; or &man.geli.8; encryption systems may be
+ used for swap encryption. Both systems use the
+ <filename>encswap</filename>
<link linkend="configtuning-rcd">rc.d</link> script.</para>
- <sect2>
- <title>Why Should Swap be Encrypted?</title>
-
- <para>Like the encryption of disk partitions, encryption of swap
- space is used to protect sensitive information. Consider an
- application that deals with passwords. As long as these
- passwords stay in physical memory, all is well. However, if
- the operating system starts swapping out memory pages to free
- space for other applications, the passwords may be written to
- the disk platters unencrypted. Encrypting swap space can be a
- solution for this scenario.</para>
- </sect2>
-
- <sect2>
- <title>Preparation</title>
-
- <note>
- <para>For the remainder of this section,
- <devicename>ad0s1b</devicename> will be the swap
- partition.</para>
- </note>
+ <note>
+ <para>For the remainder of this section,
+ <devicename>ad0s1b</devicename> will be the swap
+ partition.</para>
+ </note>
- <para>By default, swap is unencrypted. It is possible that it
- contains passwords or other sensitive data in cleartext. To
- rectify this, the data on the swap partition should be
- overwritten with random garbage:</para>
+ <para>Swap partitions are not encrypted by default and should
+ be cleared of any sensitive data before continuing. To
+ overwrite the current swap parition with random garbage,
+ execute the following command:</para>
- <screen>&prompt.root; <userinput>dd if=/dev/random of=/dev/ad0s1b bs=1m</userinput></screen>
- </sect2>
+ <screen>&prompt.root; <userinput>dd if=/dev/random of=/dev/<replaceable>ad0s1b</replaceable> bs=1m</userinput></screen>
<sect2>
<title>Swap Encryption with &man.gbde.8;</title>
@@ -3767,7 +3758,7 @@ geli_da2_flags="-p -k /root/da2.key"</programlisting>
</sect2>
<sect2>
- <title>Verifying That it Works</title>
+ <title>Encrypted Swap Verification</title>
<para>Once the system has rebooted, proper operation of the
encrypted swap can be verified using
diff --git a/en_US.ISO8859-1/books/handbook/eresources/chapter.xml b/en_US.ISO8859-1/books/handbook/eresources/chapter.xml
index af585cf8b8..0ea9b6e6a0 100644
--- a/en_US.ISO8859-1/books/handbook/eresources/chapter.xml
+++ b/en_US.ISO8859-1/books/handbook/eresources/chapter.xml
@@ -8,18 +8,18 @@
<appendix id="eresources">
<title>Resources on the Internet</title>
- <para>The rapid pace of FreeBSD progress makes print media
+ <para>The rapid pace of &os; progress makes print media
impractical as a means of following the latest developments.
Electronic resources are the best, if not often the only, way
- to stay informed of the latest advances. Since FreeBSD is a
+ to stay informed of the latest advances. Since &os; is a
volunteer effort, the user community itself also generally serves
as a <quote>technical support department</quote> of sorts, with
electronic mail, web forums, 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 mentioned here, please send them to the &a.doc; so that they
+ <para>The most important points of contact with the &os; user
+ community are outlined below. Please send other resources
+ not mentioned here to the &a.doc; so that they
may also be included.</para>
<sect1 id="eresources-mail">
@@ -27,23 +27,23 @@
<para>The mailing lists are the most direct way of addressing
questions or opening a technical discussion to a concentrated
- FreeBSD audience. There are a wide variety of lists on a number
- of different FreeBSD topics. Addressing your questions to the
+ &os; audience. There are a wide variety of lists on a number
+ of different &os; topics. Sending questions to the
most appropriate mailing list will invariably assure a faster
and more accurate 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 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
+ joining or sending mail to any list</emphasis>. Most
+ list subscribers receive many hundreds of &os; related
+ messages every day, and the charters and rules for
+ use are meant to keep the signal-to-noise ratio
of the lists high. To do less would see the mailing lists
ultimately fail as an effective communications medium for the
- project.</para>
+ Project.</para>
<note>
- <para><emphasis>If you wish to test your ability to send to
+ <para><emphasis>To test the ability to send email to
&os; lists, send a test message to &a.test.name;.</emphasis>
Please do not send test messages to any other list.</para>
</note>
@@ -61,11 +61,11 @@
<para>Archives are kept for all of the mailing lists and can be
searched using the <ulink
- url="&url.base;/search/index.html">FreeBSD World Wide Web
+ url="&url.base;/search/index.html">&os; World Wide Web
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. Note that
- this also means that messages sent to FreeBSD mailing lists
+ this also means that messages sent to &os; mailing lists
are archived in perpetuity. When protecting privacy is a
concern, consider using a disposable secondary email address
and posting only public information.</para>
@@ -89,12 +89,13 @@
<tbody>
<row>
<entry>&a.advocacy.name;</entry>
- <entry>FreeBSD Evangelism</entry>
+ <entry>&os; Evangelism</entry>
</row>
<row>
<entry>&a.announce.name;</entry>
- <entry>Important events and project milestones (moderated)</entry>
+ <entry>Important events and Project milestones
+(moderated)</entry>
</row>
<row>
@@ -105,7 +106,7 @@
<row>
<entry>&a.bugbusters.name;</entry>
<entry>Discussions pertaining to the maintenance of
- the FreeBSD problem report database and related
+ the &os; problem report database and related
tools</entry>
</row>
@@ -116,13 +117,13 @@
<row>
<entry>&a.chat.name;</entry>
- <entry>Non-technical items related to the FreeBSD
+ <entry>Non-technical items related to the &os;
community</entry>
</row>
<row>
<entry>&a.chromium.name;</entry>
- <entry>FreeBSD-specific Chromium issues</entry>
+ <entry>&os;-specific Chromium issues</entry>
</row>
<row>
@@ -134,12 +135,12 @@
<row>
<entry>&a.isp.name;</entry>
<entry>Issues for Internet Service Providers using
- FreeBSD</entry>
+ &os;</entry>
</row>
<row>
<entry>&a.jobs.name;</entry>
- <entry>FreeBSD employment and consulting
+ <entry>&os; employment and consulting
opportunities</entry>
</row>
@@ -161,7 +162,7 @@
<row>
<entry>&a.test.name;</entry>
- <entry>Where to send your test messages instead of
+ <entry>Where to send test messages instead of to
one of the actual lists</entry>
</row>
</tbody>
@@ -169,7 +170,7 @@
</informaltable>
<para><emphasis>Technical lists:</emphasis> The following
- lists are for technical discussion. You should read the
+ lists are for technical discussion. 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>
@@ -191,7 +192,7 @@
<row>
<entry>&a.afs.name;</entry>
- <entry>Porting AFS to FreeBSD</entry>
+ <entry>Porting AFS to &os;</entry>
</row>
<row>
@@ -202,7 +203,7 @@
<row>
<entry>&a.amd64.name;</entry>
- <entry>Porting FreeBSD to AMD64 systems (moderated)</entry>
+ <entry>Porting &os; to AMD64 systems (moderated)</entry>
</row>
<row>
@@ -214,22 +215,22 @@
<row>
<entry>&a.arm.name;</entry>
- <entry>Porting FreeBSD to &arm; processors</entry>
+ <entry>Porting &os; to &arm; processors</entry>
</row>
<row>
<entry>&a.atm.name;</entry>
- <entry>Using ATM networking with FreeBSD</entry>
+ <entry>Using ATM networking with &os;</entry>
</row>
<row>
<entry>&a.bluetooth.name;</entry>
- <entry>Using &bluetooth; technology in FreeBSD</entry>
+ <entry>Using &bluetooth; technology in &os;</entry>
</row>
<row>
<entry>&a.cluster.name;</entry>
- <entry>Using FreeBSD in a clustered environment</entry>
+ <entry>Using &os; in a clustered environment</entry>
</row>
<row>
@@ -240,7 +241,7 @@
<row>
<entry>&a.database.name;</entry>
<entry>Discussing database use and development under
- FreeBSD</entry>
+ &os;</entry>
</row>
<row>
@@ -250,7 +251,7 @@
<row>
<entry>&a.doc.name;</entry>
- <entry>Creating FreeBSD related documents</entry>
+ <entry>Creating &os; related documents</entry>
</row>
<row>
@@ -265,19 +266,19 @@
<row>
<entry>&a.eclipse.name;</entry>
- <entry>FreeBSD users of Eclipse IDE, tools, rich client
+ <entry>&os; users of Eclipse IDE, tools, rich client
applications and ports.</entry>
</row>
<row>
<entry>&a.embedded.name;</entry>
- <entry>Using FreeBSD in embedded applications</entry>
+ <entry>Using &os; in embedded applications</entry>
</row>
<row>
<entry>&a.eol.name;</entry>
- <entry>Peer support of FreeBSD-related software that
- is no longer supported by the FreeBSD project.</entry>
+ <entry>Peer support of &os;-related software that
+ is no longer supported by the &os; Project.</entry>
</row>
<row>
@@ -288,7 +289,7 @@
<row>
<entry>&a.firewire.name;</entry>
- <entry>FreeBSD &firewire; (iLink, IEEE 1394) technical
+ <entry>&os; &firewire; (iLink, IEEE 1394) technical
discussion</entry>
</row>
@@ -323,29 +324,29 @@
<row>
<entry>&a.hardware.name;</entry>
<entry>General discussion of hardware for running
- FreeBSD</entry>
+ &os;</entry>
</row>
<row>
<entry>&a.i18n.name;</entry>
- <entry>FreeBSD Internationalization</entry>
+ <entry>&os; Internationalization</entry>
</row>
<row>
<entry>&a.ia32.name;</entry>
- <entry>FreeBSD on the IA-32 (&intel; x86)
+ <entry>&os; on the IA-32 (&intel; x86)
platform</entry>
</row>
<row>
<entry>&a.ia64.name;</entry>
- <entry>Porting FreeBSD to &intel;'s upcoming IA64
+ <entry>Porting &os; to &intel;'s upcoming IA64
systems</entry>
</row>
<row>
<entry>&a.infiniband.name;</entry>
- <entry>Infiniband on FreeBSD</entry>
+ <entry>Infiniband on &os;</entry>
</row>
<row>
@@ -368,23 +369,17 @@
<row>
<entry>&a.java.name;</entry>
<entry>&java; developers and people porting &jdk;s to
- FreeBSD</entry>
- </row>
-
- <row>
- <entry>&a.kde.name;</entry>
- <entry>Porting <application>KDE</application> and
- <application>KDE</application> applications</entry>
+ &os;</entry>
</row>
<row>
<entry>&a.lfs.name;</entry>
- <entry>Porting LFS to FreeBSD</entry>
+ <entry>Porting LFS to &os;</entry>
</row>
<row>
<entry>&a.mips.name;</entry>
- <entry>Porting FreeBSD to &mips;</entry>
+ <entry>Porting &os; to &mips;</entry>
</row>
<row>
@@ -394,13 +389,13 @@
<row>
<entry>&a.mono.name;</entry>
- <entry>Mono and C# applications on FreeBSD</entry>
+ <entry>Mono and C# applications on &os;</entry>
</row>
<row>
<entry>&a.mozilla.name;</entry>
<entry>Porting <application>Mozilla</application> to
- FreeBSD</entry>
+ &os;</entry>
</row>
<row>
@@ -473,18 +468,18 @@
<row>
<entry>&a.ppc.name;</entry>
- <entry>Porting FreeBSD to the &powerpc;</entry>
+ <entry>Porting &os; to the &powerpc;</entry>
</row>
<row>
<entry>&a.proliant.name;</entry>
- <entry>Technical discussion of FreeBSD on HP ProLiant
+ <entry>Technical discussion of &os; on HP ProLiant
server platforms</entry>
</row>
<row>
<entry>&a.python.name;</entry>
- <entry>FreeBSD-specific Python issues</entry>
+ <entry>&os;-specific Python issues</entry>
</row>
<row>
@@ -497,12 +492,12 @@
<row>
<entry>&a.realtime.name;</entry>
<entry>Development of realtime extensions to
- FreeBSD</entry>
+ &os;</entry>
</row>
<row>
<entry>&a.ruby.name;</entry>
- <entry>FreeBSD-specific Ruby discussions</entry>
+ <entry>&os;-specific Ruby discussions</entry>
</row>
<row>
@@ -512,12 +507,12 @@
<row>
<entry>&a.security.name;</entry>
- <entry>Security issues affecting FreeBSD</entry>
+ <entry>Security issues affecting &os;</entry>
</row>
<row>
<entry>&a.small.name;</entry>
- <entry>Using FreeBSD in embedded applications
+ <entry>Using &os; in embedded applications
(obsolete; use &a.embedded.name; instead)</entry>
</row>
@@ -528,12 +523,12 @@
<row>
<entry>&a.sparc.name;</entry>
- <entry>Porting FreeBSD to &sparc; based systems</entry>
+ <entry>Porting &os; to &sparc; based systems</entry>
</row>
<row>
<entry>&a.standards.name;</entry>
- <entry>FreeBSD's conformance to the C99 and the &posix;
+ <entry>&os;'s conformance to the C99 and the &posix;
standards</entry>
</row>
@@ -544,7 +539,7 @@
<row>
<entry>&a.tcltk.name;</entry>
- <entry>FreeBSD-specific Tcl/Tk discussions</entry>
+ <entry>&os;-specific Tcl/Tk discussions</entry>
</row>
<row>
@@ -561,18 +556,18 @@
<row>
<entry>&a.threads.name;</entry>
- <entry>Threading in FreeBSD</entry>
+ <entry>Threading in &os;</entry>
</row>
<row>
<entry>&a.tilera.name;</entry>
- <entry>Porting FreeBSD to the Tilera family of
+ <entry>Porting &os; to the Tilera family of
CPUs</entry>
</row>
<row>
<entry>&a.tokenring.name;</entry>
- <entry>Support Token Ring in FreeBSD</entry>
+ <entry>Support Token Ring in &os;</entry>
</row>
<row>
@@ -599,7 +594,7 @@
<row>
<entry>&a.x11.name;</entry>
- <entry>Maintenance and support of X11 on FreeBSD</entry>
+ <entry>Maintenance and support of X11 on &os;</entry>
</row>
<row>
@@ -627,7 +622,7 @@
are for more specialized (and demanding) audiences and are
probably not of interest to the general public. It is also
a good idea to establish a presence in the technical lists
- before joining one of these limited lists so that you will
+ before joining one of these limited lists in order to
understand the communications etiquette involved.</para>
<informaltable frame="none" pgwide="1">
@@ -653,7 +648,7 @@
<row>
<entry>&a.wip-status.name;</entry>
- <entry>FreeBSD Work-In-Progress Status</entry>
+ <entry>&os; Work-In-Progress Status</entry>
</row>
<row>
@@ -667,7 +662,7 @@
<para><emphasis>Digest lists:</emphasis> All of the above lists
are available in a digest format. Once subscribed to a list,
- you can change your digest options in your account options
+ the digest options can be changed in the account options
section.</para>
<para><emphasis>SVN lists:</emphasis> The following lists
@@ -851,38 +846,38 @@
<sect2 id="eresources-subscribe">
<title>How to Subscribe</title>
- <para>To subscribe to a list, click on the list name above or
- go to &a.mailman.lists.link; and click on the list that you
- are interested in. The list page should contain all of the
- necessary subscription instructions.</para>
+ <para>To subscribe to a list, click the list name at
+ &a.mailman.lists.link;.
+ The page that is displayed should contain all of the
+ necessary subscription instructions for that list.</para>
<para>To actually post to a given list, send mail to
<email><replaceable>listname</replaceable>@FreeBSD.org</email>.
It will then be redistributed to mailing list members
world-wide.</para>
- <para>To unsubscribe yourself from a list, click on the URL
+ <para>To unsubscribe from a list, click on the URL
found at the bottom of every email received from the list.
It is also possible to send an email to
<email><replaceable>listname</replaceable>-unsubscribe@FreeBSD.org</email>
- to unsubscribe yourself.</para>
+ to unsubscribe.</para>
- <para>Again, we would like to request that you keep discussion
- in the technical mailing lists on a technical track. If you
- are only interested in important announcements then it is
- suggested that you join the &a.announce;, which is intended
- only for infrequent traffic.</para>
+ <para>It is important to keep discussion
+ in the technical mailing lists on a technical track. To
+ only receive important announcements, instead
+ join the &a.announce;, which is intended
+ for infrequent traffic.</para>
</sect2>
<sect2 id="eresources-charters">
<title>List Charters</title>
- <para><emphasis>All</emphasis> FreeBSD mailing lists have
+ <para><emphasis>All</emphasis> &os; mailing lists have
certain basic rules which must be adhered to by anyone using
them. Failure to comply with these guidelines will result
- in two (2) written warnings from the FreeBSD Postmaster
+ in two (2) written warnings from the &os; Postmaster
<email>postmaster@FreeBSD.org</email>, after which, on a
- third offense, the poster will removed from all FreeBSD
+ third offense, the poster will removed from all &os;
mailing lists and filtered from further posting to them. We
regret that such rules and measures are necessary at all,
but today's Internet is a pretty harsh environment, it would
@@ -894,8 +889,8 @@
<itemizedlist>
<listitem>
<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
+ charter of the list it is posted to. If the list
+ is about technical issues, the posting should contain
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
@@ -910,11 +905,11 @@
a great deal of subscriber overlap and except for the most
esoteric mixes (say <quote>-stable &amp; -scsi</quote>),
there really is no reason to 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 <literal>Cc</literal>
- line then the <literal>Cc</literal> line should also be
- trimmed before sending it out again. <emphasis>You are
- still responsible for your own cross-postings, no matter
+ a time. If a message is received with
+ multiple mailing lists on the <literal>Cc</literal>
+ line, trim the <literal>Cc</literal> line
+ before replying. <emphasis>The person who replies is
+ still responsible for cross-posting, no matter
who the originator might have been.</emphasis></para>
</listitem>
@@ -932,7 +927,7 @@
</listitem>
<listitem>
- <para>Advertising of non-FreeBSD related products or
+ <para>Advertising of non-&os; related products or
services is strictly prohibited and will result in an
immediate ban if it is clear that the offender is
advertising by spam.</para>
@@ -971,10 +966,10 @@
milestones</emphasis></para>
<para>This is the mailing list for people interested
- only in occasional announcements of significant FreeBSD
+ only in occasional announcements of significant &os;
events. This includes announcements about snapshots
and other releases. It contains announcements of new
- FreeBSD capabilities. It may contain calls for
+ &os; capabilities. It may contain calls for
volunteers etc. This is a low volume, strictly
moderated mailing list.</para>
</listitem>
@@ -987,7 +982,7 @@
<para><emphasis>Architecture and design
discussions</emphasis></para>
- <para>This list is for discussion of the FreeBSD
+ <para>This list is for discussion of the &os;
architecture. Messages will mostly be kept strictly
technical in nature. Examples of suitable topics
are:</para>
@@ -1020,9 +1015,9 @@
<term>&a.bluetooth.name;</term>
<listitem>
- <para><emphasis>&bluetooth; in FreeBSD</emphasis></para>
+ <para><emphasis>&bluetooth; in &os;</emphasis></para>
- <para>This is the forum where FreeBSD's &bluetooth; users
+ <para>This is the forum where &os;'s &bluetooth; users
congregate. Design issues, implementation details,
patches, bug reports, status reports, feature requests,
and all matters related to &bluetooth; are fair
@@ -1052,7 +1047,7 @@
<para><emphasis>Bug reports</emphasis></para>
<para>This is the mailing list for reporting bugs in
- FreeBSD. Whenever possible, bugs should be submitted
+ &os;. Whenever possible, bugs should be submitted
using the &man.send-pr.1; command or the <ulink
url="&url.base;/send-pr.html">WEB
interface</ulink> to it.</para>
@@ -1063,7 +1058,7 @@
<term>&a.chat.name;</term>
<listitem>
- <para><emphasis>Non technical items related to the FreeBSD
+ <para><emphasis>Non technical items related to the &os;
community</emphasis></para>
<para>This list contains the overflow from the other
@@ -1083,11 +1078,11 @@
<term>&a.chromium.name;</term>
<listitem>
- <para><emphasis>FreeBSD-specific Chromium
+ <para><emphasis>&os;-specific Chromium
issues</emphasis></para>
<para>This is a list for the discussion of Chromium
- support for FreeBSD. This is a technical list to
+ support for &os;. This is a technical list to
discuss development and installation of Chromium.</para>
</listitem>
</varlistentry>
@@ -1096,11 +1091,11 @@
<term>&a.core.name;</term>
<listitem>
- <para><emphasis>FreeBSD core team</emphasis></para>
+ <para><emphasis>&os; 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
- FreeBSD-related matter requires arbitration or
+ &os;-related matter requires arbitration or
high-level scrutiny.</para>
</listitem>
</varlistentry>
@@ -1126,10 +1121,10 @@
<term>&a.cvsweb.name;</term>
<listitem>
- <para><emphasis>FreeBSD CVSweb Project</emphasis></para>
+ <para><emphasis>&os; CVSweb Project</emphasis></para>
<para>Technical discussions about use, development and
- maintenance of FreeBSD-CVSweb.</para>
+ maintenance of &os;-CVSweb.</para>
</listitem>
</varlistentry>
@@ -1151,12 +1146,12 @@
<term>&a.doc.name;</term>
<listitem>
- <para><emphasis>Documentation project</emphasis></para>
+ <para><emphasis>Documentation Project</emphasis></para>
<para>This mailing list is for the discussion of issues
and projects related to the creation of documentation
- for FreeBSD. The members of this mailing list are
- collectively referred to as <quote>The FreeBSD
+ for &os;. The members of this mailing list are
+ collectively referred to as <quote>The &os;
Documentation Project</quote>. It is an open list;
feel free to join and contribute!</para>
</listitem>
@@ -1221,13 +1216,13 @@
<term>&a.embedded.name;</term>
<listitem>
- <para><emphasis>Using FreeBSD in embedded
+ <para><emphasis>Using &os; in embedded
applications</emphasis></para>
- <para>This list discusses topics related to using FreeBSD
+ <para>This list discusses topics related to using &os;
in embedded systems. This is a technical mailing list
for which strictly technical content is expected. For
- the purpose of this list we define embedded systems as
+ the purpose of this list, embedded systems are
those computing devices which are not desktops and which
usually serve a single purpose as opposed to being
general computing environments. Examples include, but
@@ -1255,15 +1250,15 @@
<term>&a.eol.name;</term>
<listitem>
- <para><emphasis>Peer support of FreeBSD-related software
- that is no longer supported by the FreeBSD
- project.</emphasis></para>
+ <para><emphasis>Peer support of &os;-related software
+ that is no longer supported by the &os;
+ Project.</emphasis></para>
<para>This list is for those interested in providing or
- making use of peer support of FreeBSD-related software
- for which the FreeBSD project no longer provides
- official support (e.g., in the form of security
- advisories and patches).</para>
+ making use of peer support of &os;-related software
+ for which the &os; Project no longer provides
+ official support in the form of security
+ advisories and patches.</para>
</listitem>
</varlistentry>
@@ -1276,7 +1271,7 @@
<para>This is a mailing list for discussion of the design
and implementation of a &firewire; (aka IEEE 1394 aka
- iLink) subsystem for FreeBSD. Relevant topics
+ iLink) subsystem for &os;. Relevant topics
specifically include the standards, bus devices and
their protocols, adapter boards/cards/chips sets, and
the architecture and implementation of code for their
@@ -1290,7 +1285,7 @@
<listitem>
<para><emphasis>File systems</emphasis></para>
- <para>Discussions concerning FreeBSD file systems.
+ <para>Discussions concerning &os; filesystems.
This is a technical mailing list for which strictly
technical content is expected.</para>
</listitem>
@@ -1332,7 +1327,7 @@
<para>Discussions concerning The
<application>GNOME</application> Desktop Environment
- for FreeBSD systems. This is a technical mailing list
+ for &os; systems. This is a technical mailing list
for which strictly technical content is expected.</para>
</listitem>
</varlistentry>
@@ -1356,7 +1351,7 @@
<para>This is the forum for technical discussions
concerning the redesign of the IP firewall code in
- FreeBSD. This is a technical mailing list for which
+ &os;. This is a technical mailing list for which
strictly technical content is expected.</para>
</listitem>
</varlistentry>
@@ -1365,10 +1360,10 @@
<term>&a.ia64.name;</term>
<listitem>
- <para><emphasis>Porting FreeBSD to IA64</emphasis></para>
+ <para><emphasis>Porting &os; to IA64</emphasis></para>
<para>This is a technical mailing list for individuals
- actively working on porting FreeBSD to the IA-64
+ actively working on porting &os; to the IA-64
platform from &intel;, to bring up problems or discuss
alternative solutions. Individuals interested in
following the technical discussion are also
@@ -1383,7 +1378,7 @@
<para><emphasis>ISDN Communications</emphasis></para>
<para>This is the mailing list for people discussing the
- development of ISDN support for FreeBSD.</para>
+ development of ISDN support for &os;.</para>
</listitem>
</varlistentry>
@@ -1395,7 +1390,7 @@
<para>This is the mailing list for people discussing the
development of significant &java; applications for
- FreeBSD and the porting and maintenance of
+ &os; and the porting and maintenance of
&jdk;s.</para>
</listitem>
</varlistentry>
@@ -1407,17 +1402,17 @@
<para><emphasis>Jobs offered and sought</emphasis></para>
<para>This is a forum for posting employment notices
- and resumes specifically related to &os;, e.g., if you
- are seeking &os;-related employment or have a job
- involving &os; to advertise then this is the right
- place. This is <emphasis>not</emphasis> a mailing list
+ specifically related to &os; and resumes from those
+ seeking &os;-related employment. This is
+ <emphasis>not</emphasis> a mailing list
for general employment issues since adequate forums
for that already exist elsewhere.</para>
<para>Note that this list, like other <hostid
role="domainname">FreeBSD.org</hostid> mailing lists,
- is distributed worldwide. Thus, you need to be clear
- about location and the extent to which telecommuting or
+ is distributed worldwide. Be clear
+ about the geographic location and the extent to which
+ telecommuting or
assistance with relocation is available.</para>
<para>Email should use open formats only &mdash;
@@ -1436,7 +1431,7 @@
<para><emphasis>KDE</emphasis></para>
<para>Discussions concerning
- <application>KDE</application> on FreeBSD systems.
+ <application>KDE</application> on &os; systems.
This is a technical mailing list for which strictly
technical content is expected.</para>
</listitem>
@@ -1449,8 +1444,8 @@
<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 is for individuals actively working on FreeBSD, to
+ to &os;. This is the primary technical mailing list.
+ It is for individuals actively working on &os;, to
bring up problems or discuss alternative solutions.
Individuals interested in following the technical
discussion are also welcome. This is a technical
@@ -1463,11 +1458,11 @@
<term>&a.hardware.name;</term>
<listitem>
- <para><emphasis>General discussion of FreeBSD
+ <para><emphasis>General discussion of &os;
hardware</emphasis></para>
<para>General discussion about the types of hardware
- that FreeBSD runs on, various problems and suggestions
+ that &os; runs on, various problems and suggestions
concerning what to buy or avoid.</para>
</listitem>
</varlistentry>
@@ -1479,7 +1474,7 @@
<para><emphasis>Mirror sites</emphasis></para>
<para>Announcements and discussion for people who run
- FreeBSD mirror sites.</para>
+ &os; mirror sites.</para>
</listitem>
</varlistentry>
@@ -1491,7 +1486,7 @@
Providers</emphasis></para>
<para>This mailing list is for discussing topics relevant
- to Internet Service Providers (ISPs) using FreeBSD.
+ to Internet Service Providers (ISPs) using &os;.
This is a technical mailing list for which strictly
technical content is expected.</para>
</listitem>
@@ -1502,7 +1497,7 @@
<listitem>
<para><emphasis>Mono and C# applications on
- FreeBSD</emphasis></para>
+ &os;</emphasis></para>
<para>This is a list for discussions related to the Mono
development framework on &os;. This is a technical
@@ -1535,7 +1530,7 @@
Announcements</emphasis></para>
<para>This is the mailing list for people interested in
- changes and issues related to the FreeBSD.org project
+ changes and issues related to the FreeBSD.org Project
infrastructure.</para>
<para>This moderated list is strictly for announcements: no replies,
@@ -1547,21 +1542,21 @@
<term>&a.performance.name;</term>
<listitem>
- <para><emphasis>Discussions about tuning or speedingup
- FreeBSD</emphasis></para>
+ <para><emphasis>Discussions about tuning or speeding up
+ &os;</emphasis></para>
<para>This mailing list exists to provide a place for
hackers, administrators, and/or concerned parties to
discuss performance related topics pertaining to
- FreeBSD. Acceptable topics includes talking about
- FreeBSD installations that are either under high load,
+ &os;. Acceptable topics includes talking about
+ &os; installations that are either under high load,
are experiencing performance problems, or are pushing
- the limits of FreeBSD. Concerned parties that are
+ the limits of &os;. Concerned parties that are
willing to work toward improving the performance of
- FreeBSD are highly encouraged to subscribe to this list.
+ &os; are highly encouraged to subscribe to this list.
This is a highly technical list ideally suited for
- experienced FreeBSD users, hackers, or administrators
- interested in keeping FreeBSD fast, robust, and
+ experienced &os; users, hackers, or administrators
+ interested in keeping &os; fast, robust, and
scalable. This list is not a question-and-answer list
that replaces reading through documentation, but it is a
place to make contributions or inquire about unanswered
@@ -1578,7 +1573,7 @@
filter firewall system</emphasis></para>
<para>Discussion concerning the packet filter (pf)
- firewall system in terms of FreeBSD. Technical
+ firewall system in terms of &os;. Technical
discussion and user questions are both welcome. This
list is also a place to discuss the ALTQ QoS
framework.</para>
@@ -1613,8 +1608,8 @@
<para><emphasis>Porting to Non &intel;
platforms</emphasis></para>
- <para>Cross-platform FreeBSD issues, general discussion
- and proposals for non &intel; FreeBSD ports. This is
+ <para>Cross-platform &os; issues, general discussion
+ and proposals for non &intel; &os; ports. This is
a technical mailing list for which strictly technical
content is expected.</para>
</listitem>
@@ -1627,7 +1622,7 @@
<para><emphasis>Discussion of
<quote>ports</quote></emphasis></para>
- <para>Discussions concerning FreeBSD's <quote>ports
+ <para>Discussions concerning &os;'s <quote>ports
collection</quote> (<filename>/usr/ports</filename>),
ports infrastructure, and general ports coordination
efforts. This is a technical mailing list for which
@@ -1660,7 +1655,7 @@
<para><emphasis>Discussion of
<quote>ports</quote> bugs</emphasis></para>
- <para>Discussions concerning problem reports for FreeBSD's
+ <para>Discussions concerning problem reports for &os;'s
<quote>ports collection</quote>
(<filename>/usr/ports</filename>), proposed ports, or
modific