svn commit: r41607 - projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/handbook/config
Dru Lavigne
dru at FreeBSD.org
Sun May 12 13:19:04 UTC 2013
Author: dru
Date: Sun May 12 13:19:04 2013
New Revision: 41607
URL: http://svnweb.freebsd.org/changeset/doc/41607
Log:
This patch addresses the following:
- you
- missing acronym tags
- replace command/app tags with entities
- fix links
- update some sample files
- move sysctl.conf section until after sysctl to improve the flow
of a topic not yet introduced
A subsequent patch will fix white space.
Approved by: bcr (mentor)
Modified:
projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/handbook/config/chapter.xml
Modified: projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/handbook/config/chapter.xml
==============================================================================
--- projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/handbook/config/chapter.xml Sun May 12 10:42:44 2013 (r41606)
+++ projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/handbook/config/chapter.xml Sun May 12 13:19:04 2013 (r41607)
@@ -73,7 +73,7 @@
</listitem>
<listitem>
- <para>How to tune &os; using <command>sysctl</command>
+ <para>How to tune &os; using &man.sysctl.8;
variables.</para>
</listitem>
@@ -120,30 +120,31 @@
<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
+ 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
+ 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
+ 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
+ <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
+ 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
@@ -166,8 +167,9 @@
hassle.</para>
<note>
- <para>Some users have found that &man.sysinstall.8;'s
- <literal>Auto-defaults</literal> partition sizer will
+ <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.
@@ -182,18 +184,24 @@
<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
+ 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 RAM may
+ 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 VM page scanning code and
+ 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 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
+ <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
@@ -219,10 +227,10 @@
<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
+ 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
@@ -283,21 +291,20 @@ ifconfig_fxp0="inet 10.1.1.1/8"</program
</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>
+ <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>
@@ -320,10 +327,11 @@ ifconfig_fxp0="inet 10.1.1.1/8"</program
<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
+ identified with a suffix such as <filename>.sample</filename>.
+ If
there are no existing configuration files for the application,
- they will be created by copying the
- <filename>.default</filename> files.</para>
+ they can be created by copying the
+ sample files.</para>
<para>For example, consider the contents of the directory
<filename
@@ -378,8 +386,8 @@ ifconfig_fxp0="inet 10.1.1.1/8"</program
<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,
+ 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
@@ -411,47 +419,43 @@ pidfile=${utility_pidfile-"/var/run/util
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
+ <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 the &man.rcorder.8; utility and provides for easier
+ 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
+ <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 +471,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>
@@ -477,15 +481,15 @@ run_rc_command "$1"</programlisting>
<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
+ &man.crontab.5; files. These files store
information about specific functions which
- <command>cron</command> is supposed to perform at certain
+ &man.cron.8; 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.
+ <para>Two different types of configuration files are used by
+ &man.cron.8;: 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
+ system crontab, &man.cron.8; runs 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.
@@ -499,29 +503,27 @@ run_rc_command "$1"</programlisting>
<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
+ crontab is separate from the system crontab,
+ <filename>/etc/crontab</filename>.
+ Because the system crontab
+ invokes the specified commands as <username>root</username>,
+ there is usually no
need to create a user crontab 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
#
-# $&os;: src/etc/crontab,v 1.32 2002/11/22 16:13:39 tom Exp $
+# $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 +538,51 @@ HOME=/var/log
</callout>
<callout arearefs="co-env">
- <para>First, the environment must be defined. The equals
+ <para>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
+ 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. If <envar>HOME</envar> is omitted,
- <command>cron</command> will use the invoking users home
- directory.</para>
+ 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
+ <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. 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
+ 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
@@ -591,11 +592,10 @@ HOME=/var/log
</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
+ &man.crontab.5;. However, 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>
+ &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>
@@ -604,7 +604,7 @@ HOME=/var/log
<para>Do not use the procedure described here to edit and
install the system crontab,
<filename>/etc/crontab</filename>. Instead, use an
- editor: <command>cron</command> will notice that the file
+ 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">
@@ -612,27 +612,27 @@ HOME=/var/log
</important>
<para>To install a freshly written user
- <filename>crontab</filename>, first use an editor to create
+ &man.crontab.5;, use an editor to create
and save a file in the proper format. Then, specify the file
- name with <command>crontab</command>:</para>
+ 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
+ <para>Users who wish to begin their own crontab 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 the file
is saved, it will be automatically installed by
- <command>crontab</command>.</para>
+ &man.crontab.1;.</para>
- <para>In order to remove a user <filename>crontab</filename>
+ <para>In order to remove a user &man.crontab.5;
completely, use <command>crontab -r</command>.</para>
</sect2>
</sect1>
@@ -651,105 +651,112 @@ 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
+ <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.
+ <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
+ <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
+ 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 <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
+ <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
+ <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
+ <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
+ <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
+ 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
+ <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>bgfsck</filename> script is executed, it will print
+ <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,
+ 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 then used to parse these comments
+ &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 +765,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
+ 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
+ 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
+ <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 <filename>rc.d</filename>
+ instructions on how to create custom &man.rc.8;
scripts.</para>
</sect1>
@@ -808,7 +817,8 @@ sshd is running as pid 433.</screen>
<secondary>configuration</secondary>
</indexterm>
- <para>Adding and configuring a network card is a common task for
+ <para>Adding and configuring a network interface card
+ (<acronym>NIC</acronym>) is a common task for
any &os; administrator.</para>
<sect2>
@@ -819,24 +829,31 @@ 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>If the card is supported, determine the name of the &os;
- driver for the card. Refer to
+ <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 <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: <82c169 PNIC 10/100BaseTX> port 0xa000-0xa0ff mem 0xd3800000-0xd38
000ff irq 15 at device 11.0 on pci0
@@ -853,52 +870,51 @@ bmtphy1: 10baseT, 10baseT-FDX, 100baseT
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
+ <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 interface can be
+ 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
+ <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 NIC
- drivers are available as modules; notable examples of
- devices for which modules do not exist are ISA
- cards.</para>
+ <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
+ <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
+ <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>
- <secondary>device drivers</secondary>
+ <indexterm><primary>µsoft.windows;</primary></indexterm>
+ <indexterm><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,43 +924,48 @@ 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
+ 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 the
- µsoft.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
+ using the existing driver binaries available for
+ µsoft.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 the NDISulator, three things are needed:</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
+ <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>
@@ -959,8 +980,9 @@ 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
+ <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>
@@ -976,12 +998,13 @@ 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: <Wireless-G PCI Adapter> mem 0xf4100000-0xf4101fff irq 3 at device 8.0 on pci1
@@ -990,14 +1013,14 @@ ndis0: Ethernet address: 0a:b1:2c:d3:4e:
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
+ <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 the <filename
- class="directory">/boot/modules</filename> directory. Then,
+ <filename>W32DRIVER_SYS.ko</filename>, to <filename
+ class="directory">/boot/modules</filename>. Then,
add the following line to
<filename>/boot/loader.conf</filename>:</para>
@@ -1013,12 +1036,13 @@ ndis0: 11g rates: 6Mbps 9Mbps 12Mbps 18M
<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,27 +1071,29 @@ lo0: flags=8049<UP,LOOPBACK,RUNNING,M
<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
+ <para>In this example, <devicename>dc0</devicename>
is up and running. The key indicators are:</para>
<orderedlist>
@@ -1078,32 +1104,33 @@ lo0: flags=8049<UP,LOOPBACK,RUNNING,M
<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>;
+ (<literal>netmask</literal>), where
<hostid role="netmask">0xffffff00</hostid> is the same as
- <hostid role="netmask">255.255.255.0</hostid>).</para>
+ <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
<full-duplex>)</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,39 +1157,44 @@ lo0: flags=8049<UP,LOOPBACK,RUNNING,M
<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
+ <para>The card must be configured as
+ <username>root</username>. The <acronym>NIC</acronym>
*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
More information about the svn-doc-projects
mailing list