diff options
| author | Dru Lavigne <dru@FreeBSD.org> | 2013-02-12 15:13:12 +0000 |
|---|---|---|
| committer | Dru Lavigne <dru@FreeBSD.org> | 2013-02-12 15:13:12 +0000 |
| commit | ab0bca1ad1acef071f5a26f6b5adddd193146e83 (patch) | |
| tree | ae42f92a88365a0eab69e3175059e64a8cbeae0d | |
| parent | 5abb1bd4385b28d714e469751e9b24596f076f5b (diff) | |
| download | doc-ab0bca1ad1acef071f5a26f6b5adddd193146e83.tar.gz doc-ab0bca1ad1acef071f5a26f6b5adddd193146e83.zip | |
This first patch addresses the following:
- rewording to remove you/we/please/simply/etc./i.e./as well as
- one &os; replacement
- reword sections that mention ISA
- some rewording for redundancy; some areas weren't touched as they need to be completely rewritten
- some ACPI/APM fixups
Approved by: gjb (mentor)
Notes
Notes:
svn path=/head/; revision=40959
| -rw-r--r-- | en_US.ISO8859-1/books/handbook/config/chapter.xml | 1149 |
1 files changed, 547 insertions, 602 deletions
diff --git a/en_US.ISO8859-1/books/handbook/config/chapter.xml b/en_US.ISO8859-1/books/handbook/config/chapter.xml index 1bf324e66d..c60b95c7fe 100644 --- a/en_US.ISO8859-1/books/handbook/config/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/config/chapter.xml @@ -38,25 +38,24 @@ <indexterm><primary>system configuration</primary></indexterm> <indexterm><primary>system optimization</primary></indexterm> - <para>One of the important aspects of &os; is system - configuration. Correct system configuration will help prevent - headaches during future upgrades. This chapter will explain - much of the &os; configuration process, including some of the - parameters which can be set to tune a &os; system.</para> + <para>One of the important aspects of &os; is proper system + configuration. This chapter explains much of the &os; + configuration process, including some of the parameters which + can be set to tune a &os; system.</para> <para>After reading this chapter, you will know:</para> <itemizedlist> <listitem> - <para>How to efficiently work with - file systems and swap partitions.</para> + <para>How to efficiently work with file systems and swap + partitions.</para> </listitem> <listitem> <para>The basics of <filename>rc.conf</filename> configuration and <filename class="directory">/usr/local/etc/rc.d</filename> startup - systems.</para> + scripts.</para> </listitem> <listitem> @@ -64,7 +63,7 @@ </listitem> <listitem> - <para>How to configure virtual hosts on your network + <para>How to configure virtual hosts on network devices.</para> </listitem> @@ -93,9 +92,8 @@ </listitem> <listitem> - <para>Be familiar with the basics of kernel - configuration/compilation - (<xref linkend="kernelconfig"/>).</para> + <para>Be familiar with the basics of kernel configuration and + compilation (<xref linkend="kernelconfig"/>).</para> </listitem> </itemizedlist> </sect1> @@ -133,13 +131,12 @@ <para>The size of the <filename class="directory">/var</filename> partition - reflects the intended machine usage. The - <filename class="directory">/var</filename> file system 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 will rarely need more than about a - gigabyte of free disk space in + 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> <note> @@ -158,11 +155,10 @@ </note> <para>The <filename class="directory">/usr</filename> - partition holds many of the files required to support the - system, including the &man.ports.7; collection (recommended) - and the source code (optional). Both the ports and the - sources of the base system are optional at install time, but - we recommend at least 2 gigabytes for this partition.</para> + partition holds many of the files which support the system, + including the &os; Ports Collection and system source code. + At least 2 gigabytes is recommended for this + partition.</para> <para>When selecting partition sizes, keep the space requirements in mind. Running out of space in @@ -186,20 +182,17 @@ <indexterm><primary>swap partition</primary></indexterm> <para>As a rule of thumb, the swap partition should be about - double the size of system memory (RAM). For example, if the - machine has 128 megabytes of memory, the swap file - should be 256 megabytes. Systems with less memory may - perform better with more swap. Less than 256 megabytes - of swap is not recommended and memory expansion should be - considered. The kernel's VM paging algorithms are tuned to - perform best when the swap partition is at least two times - the size of main memory. Configuring too little swap can - lead to inefficiencies in the VM page scanning code and + 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 - recommend that a swap is configured on each drive (up to + <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 @@ -219,8 +212,8 @@ characteristics and separating them allows the file system to tune accordingly. For example, the root and <filename class="directory">/usr</filename> partitions are - read-mostly, without much writing. While a lot of reading - and writing could occur in + 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> @@ -250,20 +243,18 @@ </indexterm> <para>The principal location for system configuration information - is within <filename>/etc/rc.conf</filename>. This file contains - a wide range of configuration information, principally used at - system startup to configure the system. Its name directly - implies this; it is configuration information for the - <filename>rc*</filename> files.</para> - - <para>An administrator should make entries in - <filename>rc.conf</filename> to override the default - settings from <filename>/etc/defaults/rc.conf</filename>. The - defaults file should not be copied verbatim to - <filename class="directory">/etc</filename> - it contains - default values, not examples. All system-specific changes - should be made in the <filename>rc.conf</filename> file - itself.</para> + 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> + + <para>The entries in <filename>/etc/rc.conf</filename> override + the default settings in + <filename>/etc/defaults/rc.conf</filename>. The file containing + the default settings should not be edited. Instead, all + system-specific changes should be made to + <filename>/etc/rc.conf</filename>.</para> <para>A number of strategies may be applied in clustered applications to separate site-wide configuration from @@ -306,7 +297,7 @@ ifconfig_fxp0="inet 10.1.1.1/8"</programlisting> <para>The <filename>/etc/rc.conf</filename> configuration file 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. Please see + create very complex configuration scenarios. Refer to &man.rc.conf.5; for further information on this topic.</para> </tip> </sect1> @@ -315,10 +306,10 @@ ifconfig_fxp0="inet 10.1.1.1/8"</programlisting> <title>Application Configuration</title> <para>Typically, installed applications have their own - configuration files, with their own syntax, etc. It is - important that these files be kept separate from the base - system, so that they may be easily located and managed by the - package management tools.</para> + configuration files and syntax. It is important that these + files be kept separate from the base system, so that they may be + easily located and managed by the package management + tools.</para> <indexterm><primary>/usr/local/etc</primary></indexterm> @@ -370,10 +361,9 @@ ifconfig_fxp0="inet 10.1.1.1/8"</programlisting> <indexterm><primary>services</primary></indexterm> - <para>Many users choose to install third party software on &os; - from the Ports Collection. In many of these situations it may - be necessary to configure the software in a manner which will - allow it to be started upon system initialization. Services, + <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 @@ -381,24 +371,20 @@ ifconfig_fxp0="inet 10.1.1.1/8"</programlisting> for starting third party software.</para> <para>In &os;, most included services, such as &man.cron.8;, are - started through the system start up scripts. These scripts may - differ depending on &os; or vendor version; however, the most - important aspect to consider is that their start up - configuration can be handled through simple startup - scripts.</para> + started through the system start up scripts.</para> <sect2> <title>Extended Application Configuration</title> <para>Now that &os; includes <filename>rc.d</filename>, - configuration of application startup has become easier, and - more featureful. Using the key words discussed in the + 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 may now be set to start after certain other - services for example <acronym>DNS</acronym>; may permit extra - flags to be passed through <filename>rc.conf</filename> in - place of hard coded flags in the start up script, etc. A - basic script may look similar to the following:</para> + 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 # @@ -445,8 +431,8 @@ run_rc_command "$1"</programlisting> <sect2> <title>Using Services to Start Services</title> - <para>Other services, such as <acronym>POP</acronym>3 server - daemons, <acronym>IMAP</acronym>, etc. could be started using + <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 @@ -487,14 +473,14 @@ run_rc_command "$1"</programlisting> <secondary>configuration</secondary></indexterm> <para>One of the most useful utilities in &os; is &man.cron.8;. - The <command>cron</command> utility runs in the background and - constantly checks the <filename>/etc/crontab</filename> file. - The <command>cron</command> utility also checks the - <filename class="directory">/var/cron/tabs</filename> directory, - in search of new <filename>crontab</filename> files. These - <filename>crontab</filename> files store information about - specific functions which <command>cron</command> is supposed to - perform at certain times.</para> + 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. @@ -580,23 +566,22 @@ HOME=/var/log 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 - the <filename>/etc/crontab</filename> file. This field - specifies which user the command should be run as. The last - field is the command to be executed.</para> + <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> </callout> <callout arearefs="co-main"> <para>This last line will define the values discussed above. - Notice here we have a <literal>*/5</literal> listing, - followed by several more <literal>*</literal> characters. - These <literal>*</literal> characters mean + 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. So, judging by this line, - it is apparent that <command>atrun</command> is - to be invoked by <username>root</username> every five - minutes regardless of what day or month it is. For more - information on <command>atrun</command>, see - &man.atrun.8;.</para> + <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> <para>Commands can have any number of flags passed to them; however, commands which extend to multiple lines need to be @@ -606,8 +591,8 @@ HOME=/var/log </calloutlist> <para>This is the basic setup for every - <filename>crontab</filename> file, although there is one thing - different about this one. Field number six, where we specified + <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> @@ -618,19 +603,18 @@ HOME=/var/log <important> <para>Do not use the procedure described here to edit and install the system crontab, - <filename>/etc/crontab</filename>. Just use your favorite - editor: the <command>cron</command> utility will notice that - the file has changed and immediately begin using the updated - version. See <ulink + <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. + 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 your favorite editor - to create a file in the proper format, and then use the - <command>crontab</command> utility. The most common usage - is:</para> + <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> <screen>&prompt.user; <userinput>crontab crontab-file</userinput></screen> @@ -638,21 +622,18 @@ HOME=/var/log filename of a <filename>crontab</filename> that was previously created.</para> - <para>There is also an option to list installed - <filename>crontab</filename> files: just pass the - <option>-l</option> option to <command>crontab</command> and - look over the output.</para> + <para>To list installed <filename>crontab</filename> files, pass + <option>-l</option> to <command>crontab</command>.</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 the - <command>crontab</command> command.</para> + is saved, it will be automatically installed by + <command>crontab</command>.</para> <para>In order to remove a user <filename>crontab</filename> - completely, use <command>crontab</command> with the - <option>-r</option> option.</para> + completely, use <command>crontab -r</command>.</para> </sect2> </sect1> @@ -700,13 +681,13 @@ HOME=/var/log the standard <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 the above <command>sshd restart</command> - command will only work if <varname>sshd_enable</varname> is set - to <option>YES</option> in <filename>/etc/rc.conf</filename>. + are 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 - prefixed with <quote>one</quote>. For instance to restart + prefixed with <quote>one</quote>. For instance, to restart <command>sshd</command> regardless of the current <filename>/etc/rc.conf</filename> setting, execute the following command:</para> @@ -730,9 +711,9 @@ $sshd_enable=YES</screen> <username>root</username> console.</para> </note> - <para>To determine if a service is running, a - <option>status</option> option is available. For instance to - verify that <command>sshd</command> is actually started:</para> + <para>To determine if a service is running, use + <option>status</option>. For instance, to verify that + <command>sshd</command> is running:</para> <screen>&prompt.root; <userinput>service sshd status</userinput> sshd is running as pid 433.</screen> @@ -746,9 +727,9 @@ sshd is running as pid 433.</screen> <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, consider the - <filename>bgfsck</filename> file. When this script is executed, - it will print out the following message:</para> + initialization. For instance, when the + <filename>bgfsck</filename> script is executed, it will print + out the following message:</para> <screen>Starting background file system checks in 60 seconds.</screen> @@ -802,11 +783,10 @@ sshd is running as pid 433.</screen> systems.</para> <para>Additional information about the <filename>rc.d</filename> - system can be found in the &man.rc.8; and &man.rc.subr.8; manual - pages. If you are interested in writing your own - <filename>rc.d</filename> scripts or improving the existing - ones, you may find <ulink url="&url.articles.rc-scripting">this - article</ulink> also useful.</para> + 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> + scripts.</para> </sect1> <sect1 id="config-network-setup"> @@ -828,9 +808,8 @@ sshd is running as pid 433.</screen> <secondary>configuration</secondary> </indexterm> - <para>Nowadays we can not think about a computer without thinking - about a network connection. Adding and configuring a network - card is a common task for any &os; administrator.</para> + <para>Adding and configuring a network card is a common task for + any &os; administrator.</para> <sect2> <title>Locating the Correct Driver</title> @@ -840,28 +819,24 @@ sshd is running as pid 433.</screen> <secondary>driver</secondary> </indexterm> - <para>Before you begin, you should know the model of the card - you have, the chip it uses, and whether it is a PCI or ISA - card. &os; supports a wide variety of both PCI and ISA cards. - Check the Hardware Compatibility List for your release to see - if your card is supported.</para> + <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>Once you are sure your card is supported, you need to - determine the proper driver for the card. + <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 <filename>/usr/src/sys/<replaceable>arch</replaceable>/conf/NOTES</filename> - will give you the list of network interface drivers with some - information about the supported chipsets/cards. If you have - doubts about which driver is the correct one, read the manual - page of the driver. The manual page will give you more - information about the supported hardware and even the possible - problems that could occur.</para> - - <para>If you own a common card, most of the time you will not - have to look very hard for a driver. Drivers for common - network cards are present in the <filename>GENERIC</filename> - kernel, so your card should show up during boot, like - so:</para> + for the list of network interface 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> <screen>dc0: <82c169 PNIC 10/100BaseTX> port 0xa000-0xa0ff mem 0xd3800000-0xd38 000ff irq 15 at device 11.0 on pci0 @@ -878,19 +853,20 @@ bmtphy1: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto dc1: Ethernet address: 00:a0:cc:da:da:db dc1: [ITHREAD]</screen> - <para>In this example, we see that two cards using the - &man.dc.4; driver are present on the system.</para> + <para>In this example, two cards using the &man.dc.4; driver are + present on the system.</para> - <para>If the driver for your NIC is not present in - <filename>GENERIC</filename>, you will need to load the proper - driver to use your NIC. This may be accomplished in one of - two ways:</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> <itemizedlist> <listitem> - <para>The easiest way is to simply load a kernel module for - your network card with &man.kldload.8;, or automatically - at boot time by adding the appropriate line to the file + <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 @@ -898,16 +874,15 @@ dc1: [ITHREAD]</screen> </listitem> <listitem> - <para>Alternatively, you may statically compile the support - for your card into your kernel. Check + <para>Alternatively, statically compile support for the card + 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 know what to add in - your kernel configuration file. For more information - about recompiling your kernel, please see - <xref linkend="kernelconfig"/>. If your card was detected - at boot by your kernel (<filename>GENERIC</filename>) you - do not have to build a new kernel.</para> + 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> </listitem> </itemizedlist> @@ -968,9 +943,9 @@ linuxemu/chapter.xml --> </listitem> </orderedlist> - <para>Locate the files for your specific card. Generally, + <para>Locate the files for the specific card. Generally, they can be found on the included CDs or at the vendor's - website. In the following examples, we will use + website. The following examples use <filename>W32DRIVER.SYS</filename> and <filename>W32DRIVER.INF</filename>.</para> @@ -991,12 +966,12 @@ linuxemu/chapter.xml --> <screen>&prompt.root; <userinput>kldload <replaceable>./W32DRIVER_SYS.ko</replaceable></userinput></screen> - <para>In addition to the generated kernel module, you must - load the <filename>ndis.ko</filename> and - <filename>if_ndis.ko</filename> modules. This should be - automatically done when you load any module that depends on - &man.ndis.4;. If you want to load them manually, use the - following commands:</para> + <para>In addition to the generated kernel module, the + <filename>ndis.ko</filename> and + <filename>if_ndis.ko</filename> modules must be loaded. + This should happen automatically when any module that + depends on &man.ndis.4; is loaded. If not, load them + manually, using the following commands:</para> <screen>&prompt.root; <userinput>kldload ndis</userinput> &prompt.root; <userinput>kldload if_ndis</userinput></screen> @@ -1006,7 +981,7 @@ linuxemu/chapter.xml --> interface.</para> <para>Now, check &man.dmesg.8; to see if there were any errors - loading. If all went well, you should get output resembling + loading. 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 @@ -1019,9 +994,8 @@ ndis0: 11g rates: 6Mbps 9Mbps 12Mbps 18Mbps 36Mbps 48Mbps 54Mbps</screen> <devicename>ndis0</devicename> device like any other network interface (e.g., <devicename>dc0</devicename>).</para> - <para>You can configure the system to load the NDIS modules at - boot time in the same way as with any other module. First, - copy the generated module, + <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 @@ -1044,8 +1018,8 @@ ndis0: 11g rates: 6Mbps 9Mbps 12Mbps 18Mbps 36Mbps 48Mbps 54Mbps</screen> network card may have been configured at installation time by <application>sysinstall</application>.</para> - <para>To display the configuration for the network interfaces on - your system, enter the following command:</para> + <para>To display the configuration for the network interfaces, + enter the following command:</para> <screen>&prompt.user; <userinput>ifconfig</userinput> dc0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 @@ -1128,18 +1102,18 @@ lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> metric 0 mtu 16384 <listitem> <para>The physical media selection is on autoselection mode (<literal>media: Ethernet autoselect (100baseTX - <full-duplex>)</literal>). We see that + <full-duplex>)</literal>). In this example, <devicename>dc1</devicename> was configured to run with <literal>10baseT/UTP</literal> media. For more - information on available media types for a driver, please - refer to its manual page.</para> + information on available media types for a driver, refer + to its manual page.</para> </listitem> <listitem> <para>The status of the link (<literal>status</literal>) is - <literal>active</literal>, i.e., the carrier is detected. - For <devicename>dc1</devicename>, we see - <literal>status: no carrier</literal>. This is normal + <literal>active</literal>, indicating that the carrier is + detected. For <devicename>dc1</devicename>, the + <literal>status: no carrier</literal> status is normal when an Ethernet cable is not plugged into the card.</para> </listitem> @@ -1156,44 +1130,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 your card, you need <username>root</username> - privileges. The network card configuration can be done from - the command line with &man.ifconfig.8; but you would have to - do it after each reboot of the system. The file - <filename>/etc/rc.conf</filename> is where to add the network - card's configuration.</para> - - <para>Open <filename>/etc/rc.conf</filename> in your favorite - editor. You need to add a line for each network card present - on the system, for example in our case, we added these - lines:</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. + Instead, add the network card's configuration to + <filename>/etc/rc.conf</filename> using an editor. Add a + line for each network card 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>You have to replace <devicename>dc0</devicename>, - <devicename>dc1</devicename>, and so on, with the correct - device for your cards, and the addresses with the proper ones. - You should read the card driver and &man.ifconfig.8; manual - pages for more details about the allowed options and also - &man.rc.conf.5; manual page for more information on the syntax - of <filename>/etc/rc.conf</filename>.</para> + <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 + &man.rc.conf.5; for more details about the allowed options and + the syntax of <filename>/etc/rc.conf</filename>.</para> - <para>If you configured the network during installation, some + <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>You will also have to edit the file + <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 please refer to - &man.hosts.5; and to + already there. For more information, refer to &man.hosts.5; + and to <filename>/usr/share/examples/etc/hosts</filename>.</para> <note> - <para>If access to the Internet is planned with the machine, - you also have to manually set up the default gateway and the + <para>If there is no DHCP 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> @@ -1204,12 +1174,12 @@ ifconfig_dc1="inet 10.0.0.1 netmask 255.255.255.0 media 10baseT/UTP"</programlis <sect2> <title>Testing and Troubleshooting</title> - <para>Once you have made the necessary changes in - <filename>/etc/rc.conf</filename>, you should reboot your - system. This will allow the change(s) to the interface(s) to - be applied, and verify that the system restarts without any - configuration errors. Alternatively you can just relaunch the - networking system:</para> + <para>Once the necessary changes in + <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. + Alternatively, apply the settings to the networking system + with this command:</para> <screen>&prompt.root; <userinput>service netif restart</userinput></screen> @@ -1221,8 +1191,8 @@ ifconfig_dc1="inet 10.0.0.1 netmask 255.255.255.0 media 10baseT/UTP"</programlis <screen>&prompt.root; <userinput>service routing restart</userinput></screen> </note> - <para>Once the networking system has been relaunched, you should - test the network interfaces.</para> + <para>Once the networking system has been relaunched, test the + network interfaces.</para> <sect3> <title>Testing the Ethernet Card</title> @@ -1233,10 +1203,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, - you have to try two things. First, ping the interface - itself, and then ping another machine on the LAN.</para> - - <para>First test the local interface:</para> + ping the interface itself, and then ping another machine on + the LAN:</para> <screen>&prompt.user; <userinput>ping -c5 192.168.1.3</userinput> PING 192.168.1.3 (192.168.1.3): 56 data bytes @@ -1250,8 +1218,6 @@ PING 192.168.1.3 (192.168.1.3): 56 data bytes 5 packets transmitted, 5 packets received, 0% packet loss round-trip min/avg/max/stddev = 0.074/0.083/0.108/0.013 ms</screen> - <para>Now we have to ping another machine on the LAN:</para> - <screen>&prompt.user; <userinput>ping -c5 192.168.1.2</userinput> PING 192.168.1.2 (192.168.1.2): 56 data bytes 64 bytes from 192.168.1.2: icmp_seq=0 ttl=64 time=0.726 ms @@ -1264,9 +1230,11 @@ 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>You could also use the machine name instead of - <hostid role="ipaddr">192.168.1.2</hostid> if you have set - up <filename>/etc/hosts</filename>.</para> + <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, + <filename>/etc/hosts</filename> must first be + configured.</para> </sect3> <sect3> @@ -1279,30 +1247,29 @@ round-trip min/avg/max/stddev = 0.700/0.729/0.766/0.025 ms</screen> <para>Troubleshooting hardware and software configurations is always a pain, and a pain which can be alleviated by - checking the simple things first. Is your network cable - plugged in? Have you properly configured the network - services? Did you configure the firewall correctly? Is the - card you are using supported by &os;? Always check the - hardware notes before sending off a bug report. Update your - version of &os; to the latest STABLE version. Check the - mailing list archives, or perhaps search the - Internet.</para> + 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. You - can also check the network configuration as incorrect - network settings can cause slow connections.</para> + 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>Some users experience one or two <errorname>device timeout</errorname> messages, which is normal for some cards. If they continue, or are bothersome, - you may wish to be sure the device is not conflicting with - another device. Double check the cable connections. - Perhaps you may just need to get another card.</para> + determine if the device is conflicting with another device. + 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 here is to check your network cable. Many cards + 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 @@ -1314,8 +1281,7 @@ round-trip min/avg/max/stddev = 0.700/0.729/0.766/0.025 ms</screen> 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 you are trying to reach. If there - is not, read on to + valid route to the host. If there is not, read on to <xref linkend="advanced-networking"/>.</para> <para><errorname>ping: sendto: Permission denied</errorname> @@ -1373,19 +1339,18 @@ round-trip min/avg/max/stddev = 0.700/0.729/0.766/0.025 ms</screen> <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 + 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>. - We want the system to appear at + 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 at + <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>. As noted above, - only the first address in a given network range (in this case, - <hostid role="ipaddr">10.0.1.1</hostid> and - <hostid role="ipaddr">202.0.75.17</hostid>) should have a real - netmask; all the rest (<hostid role="ipaddr">10.1.1.2</hostid> + <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 @@ -1433,8 +1398,8 @@ ifconfig_fxp0_alias7="inet 202.0.75.20 netmask 255.255.255.255"</programlisting> information to a system logging facility or other log file.</para> - <para>This section will describe how to configure and use the &os; - system logger, &man.syslogd.8;, as well as discuss log rotation + <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 @@ -1608,17 +1573,16 @@ cron.* /var/log/cron <para>Log files tend to grow quickly and accumulate steadily. This leads to the files being full of less immediately useful - information, as well as filling up the hard drive. To - mitigate this, log management comes into play. In &os;, - &man.newsyslog.8; is the tool used to manage log files. This - program is used to periodically rotate and compress log files, - as well as optionally create missing log files and signal - programs when log files are moved. The log files do not - necessarily have to come from syslog; &man.newsyslog.8; works - with any logs written from any program. It is important to - note that <command>newsyslog</command> is normally run from + information while filling up the hard drive. Log management + attempts to mitigate this. In &os;, &man.newsyslog.8; is used + 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 - configuration it is run every hour.</para> + configuration, it is run every hour.</para> <sect3> <title>Configuring @@ -1629,11 +1593,10 @@ cron.* /var/log/cron <filename>/etc/newsyslog.conf</filename>. This configuration file contains one line for each file that &man.newsyslog.8; manages. Each line states the file - owner, permissions, and when to rotate that file, as well as - optional flags that affect the log rotation (such as - compression) and programs to signal when the log is - rotated. As an example, here is the default configuration - in &os;:</para> + owner, permissions, when to rotate that file, optional flags + that affect log rotation, such as compression, and programs + to signal when the log is rotated. Here is the default + configuration in &os;:</para> <programlisting># configuration file for newsyslog # $&os;$ @@ -1676,7 +1639,7 @@ 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 followrd by an owner + 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 @@ -1841,7 +1804,7 @@ nameserver 147.11.100.30</programlisting> <literal>domain</literal> options should be used.</para> </note> - <para>If you are using DHCP, &man.dhclient.8; usually rewrites + <para>When using DHCP, &man.dhclient.8; usually rewrites <filename>resolv.conf</filename> with information received from the DHCP server.</para> </sect3> @@ -1943,12 +1906,12 @@ security.bsd.see_other_uids=0</programlisting> <secondary>with sysctl</secondary> </indexterm> - <para>&man.sysctl.8; is an interface that allows you 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> + <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> <para>At its core, &man.sysctl.8; serves two functions: to read and to modify system settings.</para> @@ -1974,11 +1937,10 @@ kern.maxfiles: 2088 -> 5000</screen> numbers, or booleans (a boolean being <literal>1</literal> for yes or a <literal>0</literal> for no).</para> - <para>If you want to automatically set some variables each time - the machine boots, add them to - <filename>/etc/sysctl.conf</filename>. For more - information see the &man.sysctl.conf.5; manual page and - <xref linkend="configtuning-sysctlconf"/>.</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 + linkend="configtuning-sysctlconf"/>.</para> <sect2 id="sysctl-readonly"> <sect2info> @@ -2039,15 +2001,15 @@ device_probe_and_attach: cbb0 attach returned 12</screen> 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 you have 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 + 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. We recommend keeping - this option on if you are running any services which - manipulate large numbers of files. Such services can + 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 @@ -2067,8 +2029,8 @@ device_probe_and_attach: cbb0 attach returned 12</screen> 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 you - may wish to turn it off.</para> + this may stall processes and under certain circumstances + should be turned off.</para> </sect3> <sect3> @@ -2082,17 +2044,17 @@ device_probe_and_attach: cbb0 attach returned 12</screen> 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 you may want to bump it up to four or - five <emphasis>megabytes</emphasis>. Note that setting too + 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. We do not recommend modifying these - values, the VM system does an extremely good job of - automatically tuning itself.</para> + related sysctls. Modifying these values is not recommended + as the VM system does an extremely good job of automatically + tuning itself.</para> </sect3> <sect3> @@ -2103,24 +2065,22 @@ device_probe_and_attach: cbb0 attach returned 12</screen> </indexterm> <para>The <varname>vm.swap_idle_enabled</varname> sysctl - variable is useful in large multi-user systems where you - have 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 - <varname>vm.swap_idle_threshold2</varname> allows you to - depress the priority of memory pages associated with idle - processes more quickly then the normal pageout algorithm. - This gives a helping hand to the pageout daemon. Do not - turn this option on unless you need it, because the tradeoff - you are making is essentially pre-page memory sooner rather - than later; thus eating 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> + 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 + <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 + helping hand to the pageout daemon. Only turn this option + on if needed, because the tradeoff is essentially pre-page + 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> </sect3> <sect3> @@ -2141,15 +2101,15 @@ device_probe_and_attach: cbb0 attach returned 12</screen> 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. You - should check the default on your system by observing the + 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, you can turn it back on by setting - the kernel variable back to 1. This must be done from the - boot loader at boot time. Attempting to do it after the - kernel boots will have no effect.</para> + 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> - <para>For more information, please see &man.ata.4;.</para> + <para>For more information, refer to &man.ata.4;.</para> </sect3> <sect3> @@ -2336,9 +2296,9 @@ device_probe_and_attach: cbb0 attach returned 12</screen> foreground <command>fsck</command> though.)</para> <para>The advantage is that meta-data operations are nearly - as fast as asynchronous updates (i.e., faster than with + as fast as asynchronous updates which are, faster than <emphasis>logging</emphasis>, which has to write the - meta-data twice). The disadvantages are the complexity of + 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 @@ -2378,28 +2338,27 @@ device_probe_and_attach: cbb0 attach returned 12</screen> </indexterm> <para><varname>kern.maxfiles</varname> can be raised or - lowered based upon your system requirements. This variable - indicates the maximum number of file descriptors on your + 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 - with the <command>dmesg</command> command.</para> + using <command>dmesg</command>.</para> <para>Each open file, socket, or fifo uses one file descriptor. A large-scale production server may easily require many thousands of file descriptors, depending on the kind and number of services running concurrently.</para> - <para>In older FreeBSD releases, the default value of - <varname>kern.maxfiles</varname> is derived from the - <option>maxusers</option> option in your kernel - configuration file. <varname>kern.maxfiles</varname> grows - proportionally to the value of <option>maxusers</option>. - When compiling a custom kernel, it is a good idea to set - this kernel configuration option according to the uses of - your system. From this number, the kernel is given most of - its pre-defined limits. Even though a production machine - may not actually have 256 users connected at once, the + <para>In older &os; releases, the default value of + <varname>kern.maxfiles</varname> is derived from + <option>maxusers</option> in the kernel configuration file. + <varname>kern.maxfiles</varname> grows proportionally to the + value of <option>maxusers</option>. When compiling a custom + kernel, consider setting this kernel configuration option + according to the use of the system. From this number, the + kernel is given most of its pre-defined limits. Even though + a production machine may not have 256 concurrent users, the resources needed may be similar to a high-scale web server.</para> @@ -2410,52 +2369,52 @@ device_probe_and_attach: cbb0 attach returned 12</screen> <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. We do - not recommend going above 256 unless you need a huge number - of file descriptors; many of the tunable values set to their - defaults by <varname>kern.maxusers</varname> may be + 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 - <filename>/boot/loader.conf</filename> (see the - &man.loader.conf.5; manual page or - <filename>/boot/defaults/loader.conf</filename> for - some hints) or as described elsewhere in this - document.</para> + <filename>/boot/loader.conf</filename>. Refer to + &man.loader.conf.5; and + <filename>/boot/defaults/loader.conf</filename> for more + details and some hints.</para> <para>In older releases, the system will auto-tune - <literal>maxusers</literal> for you if you explicitly set it - to <literal>0</literal> + <literal>maxusers</literal> if it is set to + <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, you will want to set <literal>maxusers</literal> to - at least 4, especially if you are using the X Window System - or compiling software. The reason is that the most - important table set by <literal>maxusers</literal> is the - maximum number of processes, which is set to - <literal>20 + 16 * maxusers</literal>, so if you set - <literal>maxusers</literal> to 1, then you can only have 36 - simultaneous processes, including the 18 or so that the - system starts up at boot time and the 15 or so you will - probably create when you start the X Window System. Even a - simple task like reading a manual page will start up nine - processes to filter, decompress, and view it. Setting - <literal>maxusers</literal> to 64 will allow you to have up - to 1044 simultaneous processes, which should be enough for - nearly all uses. If, however, you see the dreaded + option, set <literal>maxusers</literal> to at least 4, + 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 + 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>), you can - always increase the number and rebuild.</para> + <hostid role="fqdn">ftp.FreeBSD.org</hostid>), 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 sizes to reasonable values considering the maximum number - of users you will likely have on your system and how many - processes each of them will be running.</para> + of users on the system and how many processes each user + will be running.</para> </note> </sect3> @@ -2492,23 +2451,22 @@ device_probe_and_attach: cbb0 attach returned 12</screen> 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. If you have a web server which maxes out at - 1000 simultaneous connections, and each connection eats a - 16 K receive and 16 K send buffer, you need + 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 2x32 MB / 2 KB = - 64 MB / 2 kB = 32768. We recommend - values between 4096 and 32768 for machines with greater + 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. The <option>-m</option> option to - &man.netstat.1; may be used to observe network cluster - use.</para> + to a boot time crash. To observe network cluster usage, use + <option>-m</option> with &man.netstat.1;.</para> - <para><varname>kern.ipc.nmbclusters</varname> loader tunable + <para>The <varname>kern.ipc.nmbclusters</varname> loader tunable should be used to tune this at boot time. Only older versions - of &os; will require you to use the + of &os; will require the use of the <literal>NMBCLUSTERS</literal> kernel &man.config.8; option.</para> @@ -2550,17 +2508,17 @@ device_probe_and_attach: cbb0 attach returned 12</screen> 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 you are 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 you may run - yourself out of ports, it is recommended to increase + 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 <varname>net.inet.ip.portrange.last</varname> modestly. A value of <literal>10000</literal>, <literal>20000</literal> - or <literal>30000</literal> may be reasonable. You should - also consider firewall effects when changing the port range. - Some firewalls may block large ranges of ports (usually + 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 @@ -2584,27 +2542,25 @@ device_probe_and_attach: cbb0 attach returned 12</screen> 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 if you are serving data over - modems, Gigabit Ethernet, or even high speed WAN links (or - any other link with a high bandwidth delay product), - especially if you are also using window scaling or have - configured a large send window. If you enable this option, - you should also be sure to set - <varname>net.inet.tcp.inflight.debug</varname> to + <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 as well as - reduces the amount of data built up in the local host's - interface queue. With fewer packets queued up, interactive - connections, especially over slow modems, will also be able - to operate with lower <emphasis>Round Trip Times</emphasis>. - However, note that this feature only effects data - transmission (uploading / server side). It has no effect on - data reception (downloading).</para> + 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> <para>Adjusting <varname>net.inet.tcp.inflight.stab</varname> is <emphasis>not</emphasis> recommended. This parameter @@ -2612,12 +2568,11 @@ device_probe_and_attach: cbb0 attach returned 12</screen> 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 you would get without the inflight - algorithm). In such cases, you may wish to try reducing - this parameter to 15, 10, or 5; and may also have to reduce - <varname>net.inet.tcp.inflight.min</varname> (for example, - to 3500) to get the desired effect. Reducing these + 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> </sect3> </sect2> @@ -2662,14 +2617,14 @@ kern.maxvnodes: 100000</screen> <sect1 id="adding-swap-space"> <title>Adding Swap Space</title> - <para>No matter how well you plan, sometimes a system does not run - as you expect. If you find you need more swap space, it is - simple enough to add. You have three ways to increase swap - space: adding a new hard drive, enabling swap over NFS, and - creating a swap file on an existing partition.</para> + <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>For information on how to encrypt swap space, what options - for this task exist and why it should be done, please refer to + for this task exist and why it should be done, refer to <xref linkend="swap-encrypting"/> of the Handbook.</para> <sect2 id="new-drive-swap"> @@ -2720,9 +2675,8 @@ kern.maxvnodes: 100000</screen> <title>Swapfiles</title> <para>You can create a file of a specified size to use as a swap - file. In our example here we will use a 64MB file called - <filename>/usr/swap0</filename>. You can use any name you - want, of course.</para> + file. The following example will create a 64MB file named + <filename>/usr/swap0</filename>.</para> <example> <title>Creating a Swapfile on &os;</title> @@ -2733,13 +2687,13 @@ 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 your custom + sure to include the following line in the custom configuration file:</para> <programlisting>device md</programlisting> - <para>For information on building your own kernel, please - refer to <xref linkend="kernelconfig"/>.</para> + <para>For information on building a custom kernel, refer + to <xref linkend="kernelconfig"/>.</para> </listitem> <listitem> @@ -2792,22 +2746,22 @@ kern.maxvnodes: 100000</screen> <title>Power and Resource Management</title> <para>It is important to utilize hardware resources in an - efficient manner. Before <acronym>ACPI</acronym> was - introduced, it was difficult and inflexible for operating - systems to manage the power usage and thermal properties of a - system. The hardware was managed by the <acronym>BIOS</acronym> - and thus 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. For example, you may want an operating system - to monitor system limits (and possibly alert you) in case your - system temperature increased unexpectedly.</para> - - <para>In this section of the &os; Handbook, we will provide - comprehensive information about <acronym>ACPI</acronym>. - References will be provided for further reading at the - end.</para> + efficient manner. Before the Advanced Configuration and Power + Interface (<acronym>ACPI</acronym>) was introduced, it was + difficult and inflexible for operating systems to manage the + power usage and thermal properties of a system. The hardware + 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 + temperature increases unexpectedly.</para> + + <para>This section provides comprehensive information about + <acronym>ACPI</acronym>. References will be provided for further + reading.</para> <sect2 id="acpi-intro"> <title>What Is ACPI?</title> @@ -2820,32 +2774,29 @@ kern.maxvnodes: 100000</screen> <primary>APM</primary> </indexterm> - <para>Advanced Configuration and Power Interface - (<acronym>ACPI</acronym>) is a standard written by an alliance - of vendors to provide a standard interface for hardware - resources and power management (hence the name). It is a key + <para><acronym>ACPI</acronym> is a standard written by an + alliance of vendors to provide a standard interface for + hardware resources and power management. It is a key element in <emphasis>Operating System-directed configuration - and Power Management</emphasis>, i.e.: it provides more - control and flexibility to the operating system - (<acronym>OS</acronym>). Modern systems + and Power Management</emphasis> as it provides more control + and flexibility to the operating system. Modern systems <quote>stretched</quote> the limits of the current Plug and Play interfaces prior to the introduction of <acronym>ACPI</acronym>. <acronym>ACPI</acronym> is the - direct successor to <acronym>APM</acronym> (Advanced Power - Management).</para> + direct successor to <acronym>APM</acronym>.</para> </sect2> <sect2 id="acpi-old-spec"> <title>Shortcomings of Advanced Power Management (APM)</title> - <para>The <emphasis>Advanced Power Management (APM)</emphasis> - facility controls the power usage of a system based on its - activity. The APM BIOS is supplied by the (system) vendor and - it is specific to the hardware platform. An APM driver in the - OS 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>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 @@ -2886,7 +2837,7 @@ kern.maxvnodes: 100000</screen> 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, - you can disable <acronym>ACPI</acronym> altogether. This + <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 @@ -2956,11 +2907,10 @@ kern.maxvnodes: 100000</screen> &intel; <acronym>ACPI-CA</acronym> interpreter continue to appear.</para> - <para>This document is intended to help you assist the &os; + <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 - solution. Thanks for reading this and we hope we can solve your - system's problems.</para> + solution.</para> <sect2 id="ACPI-submitdebug"> <title>Submitting Debugging Information</title> @@ -2971,23 +2921,22 @@ kern.maxvnodes: 100000</screen> embedded controller firmware version.</para> </note> - <para>For those of you that want to submit a problem right away, - please send the following information to - <ulink url="mailto:freebsd-acpi@FreeBSD.org"> + <para>When submitting a problem, send the following information + to <ulink url="mailto:freebsd-acpi@FreeBSD.org"> freebsd-acpi@FreeBSD.org</ulink>:</para> <itemizedlist> <listitem> <para>Description of the buggy behavior, including system type and model and anything that causes the bug to appear. - Also, please note as accurately as possible when the bug - began occurring if it is new for you.</para> + Note as accurately as possible when the bug began + occurring if it is new.</para> </listitem> <listitem> <para>The &man.dmesg.8; output after <command>boot -v</command>, including any error messages - generated by you exercising the bug.</para> + generated by the bug.</para> </listitem> <listitem> @@ -2998,17 +2947,17 @@ kern.maxvnodes: 100000</screen> <listitem> <para>Output from <command>sysctl hw.acpi</command>. This - is also a good way of figuring out what features your + is also a good way of figuring out what features the system offers.</para> </listitem> <listitem> - <para><acronym>URL</acronym> where your + <para><acronym>URL</acronym> where the <firstterm><acronym>ACPI</acronym> Source Language</firstterm> (<acronym>ASL</acronym>) can be found. Do <emphasis>not</emphasis> send the <acronym>ASL</acronym> directly to the list as it can be - very large. Generate a copy of your + 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> @@ -3020,18 +2969,16 @@ kern.maxvnodes: 100000</screen> </listitem> </itemizedlist> - <para>Most of the developers watch the &a.current; - but please submit problems to &a.acpi.name; to be sure it is - seen. Please be patient, all of us have full-time jobs - elsewhere. If your bug is not immediately apparent, we will - probably ask you to submit a <acronym>PR</acronym> via - &man.send-pr.1;. When entering a <acronym>PR</acronym>, - please include the same information as requested above. This - will help us track the problem and resolve it. Do not send a - <acronym>PR</acronym> without emailing &a.acpi.name; first as - we use <acronym>PR</acronym>s as reminders of existing - problems, not a reporting mechanism. It is likely that your - problem has been reported by someone before.</para> + <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 + <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 + and resolve it. Do not send a <acronym>PR</acronym> without + emailing &a.acpi.name; first as it is likely that the problem + has been reported before.</para> </sect2> <sect2 id="ACPI-background"> @@ -3100,8 +3047,8 @@ kern.maxvnodes: 100000</screen> 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 then please consider sending a bug report as - described above.</para> + not work, consider sending a bug report using + &man.send-pr.1;.</para> </sect3> <sect3> @@ -3112,7 +3059,7 @@ kern.maxvnodes: 100000</screen> <literal>S1</literal>-<literal>S3</literal>, and one suspend to disk state (<literal>STD</literal>), called <literal>S4</literal>. <literal>S5</literal> is - <quote>soft off</quote> and is the normal state your system + <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> @@ -3127,27 +3074,26 @@ kern.maxvnodes: 100000</screen> <screen>hw.acpi.supported_sleep_state: S3 S4 S5 hw.acpi.s4bios: 0</screen> - <para>This means that we can use - <command>acpiconf -s</command> to test + <para>Use <command>acpiconf -s</command> to test <literal>S3</literal>, <literal>S4</literal><acronym>OS</acronym>, and - <literal>S5</literal>. If <option>s4bios</option> was one - (<literal>1</literal>), we would have + <literal>S5</literal>. An <option>s4bios</option> of one + (<literal>1</literal>), indicates <literal>S4</literal><acronym>BIOS</acronym> support instead of <literal>S4</literal> <acronym>OS</acronym>.</para> <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> but - if you have it, it is similar to <literal>S1</literal>. The - next thing to try is <literal>S3</literal>. This is the - deepest <acronym>STR</acronym> state and requires a lot of - driver support to properly reinitialize your hardware. If - you have problems resuming, feel free to email the - &a.acpi.name; list but do not expect the problem to be - resolved since there are a lot of drivers/hardware that need - more testing and work.</para> + 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 + <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 + of drivers and hardware that need more testing and + work.</para> <para>A common problem with suspend/resume is that many device drivers do not save, restore, or reinitialize their @@ -3160,32 +3106,33 @@ hw.acpi.s4bios: 0</screen> <para>This test emulates suspend/resume cycle of all device drivers without actually going into <literal>S3</literal> - state. In some cases, you can easily catch problems with - this method (e.g., losing firmware state, device watchdog - time out, and retrying forever). Note that the system will + 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, i.e., serial - port/cable for serial console or Firewire port/cable for - &man.dcons.4;, and kernel debugging skills.</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> <para>To help isolate the problem, remove as many drivers from - your kernel as possible. If it works, you can narrow down - which driver is the problem by loading drivers until it - fails again. Typically binary drivers like - <filename>nvidia.ko</filename>, X11 display drivers, and + 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 + <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, you can automate this by putting - the appropriate commands in + load/unload the drivers, 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 your display is messed up after + (<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> @@ -3196,14 +3143,13 @@ hw.acpi.s4bios: 0</screen> 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 (e.g., sound, - <acronym>ATA</acronym>, etc.) so any work done on tracking + 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. If you are feeling adventurous, go ahead and - start putting some debugging &man.printf.3;s in a - problematic driver to track down where in its resume - function it hangs.</para> + 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>Finally, try disabling <acronym>ACPI</acronym> and enabling <acronym>APM</acronym> instead. If suspend/resume @@ -3235,7 +3181,7 @@ hw.acpi.s4bios: 0</screen> <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, you have an interrupt + at more than a couple per second, there is an interrupt storm. If the system appears hung, try breaking to <acronym>DDB</acronym> (<keycombo action="simul"> <keycap>CTRL</keycap> @@ -3249,8 +3195,8 @@ hw.acpi.s4bios: 0</screen> <secondary>disabling</secondary> </indexterm> - <para>Your best hope when dealing with interrupt problems is - to try disabling <acronym>APIC</acronym> support with + <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> </sect3> @@ -3264,16 +3210,16 @@ hw.acpi.s4bios: 0</screen> 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 - up a &man.dump.8; partition. You can get a backtrace in - <acronym>DDB</acronym> with <literal>tr</literal>. If you - have to handwrite the backtrace, be sure to at least get the - lowest five (5) and top five (5) lines in the trace.</para> + 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> <para>Then, try to isolate the problem by booting with - <acronym>ACPI</acronym> disabled. If that works, you can - isolate the <acronym>ACPI</acronym> subsystem by using - various values of <option>debug.acpi.disable</option>. See - the &man.acpi.4; manual page for some examples.</para> + <acronym>ACPI</acronym> disabled. If that works, isolate + the <acronym>ACPI</acronym> subsystem by using various + values of <option>debug.acpi.disable</option>. See + &man.acpi.4; for some examples.</para> </sect3> <sect3> @@ -3292,13 +3238,13 @@ hw.acpi.s4bios: 0</screen> <sect3> <title>Other Problems</title> - <para>If you have other problems with <acronym>ACPI</acronym> - (working with a docking station, devices not detected, - etc.), please email a description to the mailing list as - well; however, some of these issues may be related to - unfinished parts of the <acronym>ACPI</acronym> subsystem so - they might take a while to be implemented. Please be - patient and prepared to test patches we may send you.</para> + <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 + 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 + patches.</para> </sect3> </sect2> @@ -3319,27 +3265,28 @@ hw.acpi.s4bios: 0</screen> <screen>ACPI-1287: *** Error: Method execution failed [\\_SB_.PCI0.LPC0.FIGD._STA] \\ (Node 0xc3f6d160), AE_NOT_FOUND</screen> - <para>Often, you can resolve these problems by updating your + <para>Often, these problems may be resolved by updating the <acronym>BIOS</acronym> to the latest revision. Most console - messages are harmless but if you have other problems like - battery status not working, they 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 your - <acronym>ASL</acronym>, use &man.acpidump.8;. You should use - both the <option>-t</option> (show contents of the fixed - tables) and <option>-d</option> (disassemble - <acronym>AML</acronym> to <acronym>ASL</acronym>) options. - See the <link linkend="ACPI-submitdebug">Submitting Debugging - Information</link> section for an example syntax.</para> - - <para>The simplest first check you can do is to recompile your + 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> + + <para>The simplest first check is to recompile the <acronym>ASL</acronym> to check for errors. Warnings can - usually be ignored but errors are bugs that will usually + usually be ignored, but errors are bugs that will usually prevent <acronym>ACPI</acronym> from working correctly. To - recompile your <acronym>ASL</acronym>, issue the following + recompile the <acronym>ASL</acronym>, issue the following command:</para> <screen>&prompt.root; <userinput>iasl your.asl</userinput></screen> @@ -3353,26 +3300,26 @@ hw.acpi.s4bios: 0</screen> <secondary>ASL</secondary> </indexterm> - <para>In the long run, our goal is for almost everyone to have - <acronym>ACPI</acronym> work without any user intervention. - At this point, however, we are still developing workarounds - for common mistakes made by the <acronym>BIOS</acronym> - vendors. The µsoft; interpreter + <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 <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>. We hope to continue to identify and - document exactly what non-standard behavior is allowed by + <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 us identify behavior, you can fix the - <acronym>ASL</acronym> manually. If this works for you, - please send a &man.diff.1; of the old and new - <acronym>ASL</acronym> so we can possibly work around the - buggy behavior in <acronym>ACPI-CA</acronym> and thus make - your fix unnecessary.</para> + 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> <indexterm> <primary>ACPI</primary> @@ -3400,40 +3347,39 @@ 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. You can also add explicit - Return statements where required if you know what value - should be returned. To force <command>iasl</command> to - compile the <acronym>ASL</acronym>, use the - <option>-f</option> flag.</para> + 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 + <acronym>ASL</acronym>, use the <option>-f</option> + flag.</para> </sect3> <sect3> <title>Overriding the Default <acronym>AML</acronym></title> - <para>After you customize <filename>your.asl</filename>, you - will want to compile it, run:</para> + <para>After customizing <filename>your.asl</filename>, compile + it with this command:</para> <screen>&prompt.root; <userinput>iasl your.asl</userinput></screen> - <para>You can add the <option>-f</option> flag to force - creation of the <acronym>AML</acronym>, even if there are - errors during compilation. Remember that some errors (e.g., - missing Return statements) are automatically worked around - by the interpreter.</para> + <para>Adding the <option>-f</option> flag will force creation + of the <acronym>AML</acronym>, even if there are errors + 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>. You can load this - instead of your <acronym>BIOS</acronym>'s buggy copy (which - is still present in flash memory) by editing + 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> <programlisting>acpi_dsdt_load="YES" acpi_dsdt_name="/boot/DSDT.aml"</programlisting> - <para>Be sure to copy your <filename>DSDT.aml</filename> to - the <filename class="directory">/boot</filename> - directory.</para> + <para>Be sure to copy <filename>DSDT.aml</filename> to + <filename class="directory">/boot</filename>.</para> </sect3> </sect2> @@ -3452,27 +3398,27 @@ acpi_dsdt_name="/boot/DSDT.aml"</programlisting> </indexterm> <para>The <acronym>ACPI</acronym> driver has a very flexible - debugging facility. It allows you to specify a set of - subsystems as well as the level of verbosity. The subsystems - you wish to debug are specified as <quote>layers</quote> and - are broken down into <acronym>ACPI-CA</acronym> components - (ACPI_ALL_COMPONENTS) and <acronym>ACPI</acronym> hardware - support (ACPI_ALL_DRIVERS). The verbosity of debugging output - is specified as the <quote>level</quote> and ranges from + 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 + <acronym>ACPI-CA</acronym> components (ACPI_ALL_COMPONENTS) + and <acronym>ACPI</acronym> hardware support + (ACPI_ALL_DRIVERS). The verbosity of debugging output is + specified as the <quote>level</quote> and ranges from 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, you will want to use a serial console 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 - the &man.acpi.4; manual page.</para> + 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 + &man.acpi.4;.</para> <para>Debugging output is not enabled by default. To enable it, - add <literal>options ACPI_DEBUG</literal> to your kernel + add <literal>options ACPI_DEBUG</literal> to the kernel configuration file if <acronym>ACPI</acronym> is compiled into - the kernel. You can add <literal>ACPI_DEBUG=1</literal> to - your <filename>/etc/make.conf</filename> to enable it - globally. If it is a module, you can recompile just your + 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>acpi.ko</filename> module as follows:</para> <screen>&prompt.root; <userinput>cd /sys/modules/acpi/acpi @@ -3481,22 +3427,21 @@ make ACPI_DEBUG=1</userinput></screen> <para>Install <filename>acpi.ko</filename> in <filename class="directory">/boot/kernel</filename> and add - your desired level and layer to + 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 - (<acronym>CPU</acronym>, <acronym>LID</acronym>, etc.). It - will only output error messages, the least verbose - level.</para> + <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> <programlisting>debug.acpi.layer="ACPI_ALL_COMPONENTS ACPI_ALL_DRIVERS" debug.acpi.level="ACPI_LV_ERROR"</programlisting> - <para>If the information you want is triggered by a specific - event (say, a suspend and then resume), you can leave out - changes to <filename>loader.conf</filename> and instead use + <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 your system for the specific event. The + 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> </sect2> |