diff options
Diffstat (limited to 'en_US.ISO8859-1/books/handbook/config/chapter.xml')
| -rw-r--r-- | en_US.ISO8859-1/books/handbook/config/chapter.xml | 2450 |
1 files changed, 1222 insertions, 1228 deletions
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 # -# $&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 +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: <82c169 PNIC 10/100BaseTX> 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>µsoft.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 - µ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 - 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 µ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 &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: <Wireless-G PCI Adapter> 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<UP,LOOPBACK,RUNNING,MULTICAST> 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<UP,LOOPBACK,RUNNING,MULTICAST> 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 <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,41 +1111,40 @@ lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> 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>"' >> /etc/rc.conf</userinput> &prompt.root; <userinput>echo 'nameserver <replaceable>your_DNS_server</replaceable>' >> /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># $&os;$ # @@ -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 -# $&os;$ +# $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># $&os;$ # @@ -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 -> 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 -> 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 K) in the file system and less - (typically 512 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 K) rather than 512 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 K) + in the file system and typically 512 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 K) + rather than 512 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; 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 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 K receive and 16 K send buffer, requires - approximately 32 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 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 K receive and 16 K send buffer, + requires approximately 32 MB worth of network buffers + to cover the web server. A good rule of thumb is to multiply + by <literal>2</literal>, so 2x32 MB / 2 KB = - 64 MB / 2 kB = 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 MB / 2 kB = + <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 — 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 && 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 > <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 µsoft; 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 + µsoft; 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 - µsoft;'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 + µsoft;'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 && make clean && 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> |