2 The FreeBSD Documentation Project
4 $FreeBSD: /usr/local/www/cvsroot/FreeBSD/doc/en_US.ISO8859-1/books/handbook/config/chapter.sgml,v 1.169 2004/08/27 12:04:24 blackend Exp $
5 $DragonFly: doc/en/books/handbook/config/chapter.sgml,v 1.11 2006/07/12 04:00:59 justin Exp $
8 <chapter id="config-tuning">
12 <firstname>Chern</firstname>
13 <surname>Lee</surname>
14 <contrib>Written by </contrib>
19 <firstname>Mike</firstname>
20 <surname>Smith</surname>
21 <contrib>Based on a tutorial written by </contrib>
26 <firstname>Matt</firstname>
27 <surname>Dillon</surname>
28 <contrib>Also based on tuning(7) written by </contrib>
33 <title>Configuration and Tuning</title>
35 <sect1 id="config-synopsis">
36 <title>Synopsis</title>
38 <indexterm><primary>system configuration</primary></indexterm>
39 <indexterm><primary>system optimization</primary></indexterm>
41 <para>One of the important aspects of &os; is system configuration.
42 Correct system configuration will help prevent headaches during future upgrades.
43 This chapter will explain much of the &os; configuration process,
44 including some of the parameters which
45 can be set to tune a &os; system.
48 <para>After reading this chapter, you will know:
52 <para>How to efficiently work with
53 file systems and swap partitions.</para>
56 <para>The basics of <filename>rc.conf</filename> configuration and
57 <filename>rc.d</filename> startup systems.</para>
60 <para>How to configure and test a network card.</para>
63 <para>How to configure virtual hosts on your network devices.</para>
66 <para>How to use the various configuration files in
67 <filename>/etc</filename>.</para>
70 <para>How to tune &os; using <command>sysctl</command>
74 <para>How to tune disk performance and modify kernel
80 <para>Before reading this chapter, you should:
84 <para>Understand &unix; and &os; basics (<xref
85 linkend="basics">).</para>
88 <para>Be familiar with the basics of kernel configuration/compilation
89 (<xref linkend="kernelconfig">).</para>
95 <sect1 id="configtuning-initial">
96 <title>Initial Configuration</title>
99 <title>Partition Layout</title>
101 <indexterm><primary>partition layout</primary></indexterm>
103 <primary><filename>/etc</filename></primary>
106 <primary><filename>/var</filename></primary>
109 <primary><filename>/usr</filename></primary>
113 <title>Base Partitions</title>
115 <para>When laying out file systems with &man.disklabel.8;
117 drives transfer data faster from the outer
119 Thus smaller and heavier-accessed file systems
120 should be closer to the outside of the drive, while
121 larger partitions like <filename>/usr</filename> should be placed
122 toward the inner. It is a good idea to create
123 partitions in a similar order to: root, swap,
124 <filename>/var</filename>, <filename>/usr</filename>.</para>
126 <para>The size of <filename>/var</filename>
127 reflects the intended machine usage.
128 <filename>/var</filename> is used to hold
129 mailboxes, log files, and printer spools. Mailboxes and log
130 files can grow to unexpected sizes depending
131 on how many users exist and how long log
132 files are kept. Most users would never require a gigabyte,
133 but remember that <filename>/var/tmp</filename>
134 must be large enough to contain packages.
137 <para>The <filename>/usr</filename> partition holds much
138 of the files required to support the system, the &pkgsrc;
139 collection (recommended) and the source code (optional).
140 At least 2 gigabytes would be recommended for this partition.</para>
142 <para>When selecting partition sizes, keep the space
143 requirements in mind. Running out of space in
144 one partition while barely using another can be a
147 <!-- todo: reed: fix this for the new installer, if it applies
148 <note><para>Some users have found that &man.sysinstall.8;'s
149 <literal>Auto-defaults</literal> partition sizer will
150 sometimes select smaller than adequate <filename>/var</filename>
151 and <filename>/</filename> partitions. Partition wisely and
152 generously.</para></note>
157 <sect3 id="swap-design">
158 <title>Swap Partition</title>
160 <indexterm><primary>swap sizing</primary></indexterm>
161 <indexterm><primary>swap partition</primary></indexterm>
163 <para>As a rule of thumb, the swap partition should be
164 about double the size of system memory (RAM). For example,
165 if the machine has 128 megabytes of memory,
166 the swap file should be 256 megabytes. Systems with
167 less memory may perform better with more swap.
168 Less than 256 megabytes of swap is not recommended and
169 memory expansion should be considered.
170 The kernel's VM paging algorithms are tuned to
171 perform best when the swap partition is at least two times the
172 size of main memory. Configuring too little swap can lead to
173 inefficiencies in the VM page scanning code and might create
174 issues later if more memory is added.</para>
176 <para>On larger systems with multiple SCSI disks (or
177 multiple IDE disks operating on different controllers), it is
178 recommend that a swap is configured on each drive (up
179 to four drives). The swap partitions should be
180 approximately the same size. The kernel can handle arbitrary
181 sizes but internal data structures scale to 4 times the
182 largest swap partition. Keeping the swap partitions near the
183 same size will allow the kernel to optimally stripe swap space
185 Large swap sizes are fine, even if swap is not
186 used much. It might be easier to recover
187 from a runaway program before being forced to reboot.</para>
191 <title>Why Partition?</title>
193 <para>Several users think a single large partition will be fine,
194 but there are several reasons why this is a bad idea.
195 First, each partition has different operational
196 characteristics and separating them allows the file system to
197 tune accordingly. For example, the root
198 and <filename>/usr</filename> partitions are read-mostly, without
199 much writing. While a lot of reading and writing could
200 occur in <filename>/var</filename> and
201 <filename>/var/tmp</filename>.</para>
203 <para>By properly partitioning a system, fragmentation
204 introduced in the smaller write heavy partitions
205 will not bleed over into the mostly-read partitions.
206 Keeping the write-loaded partitions closer to
209 increase I/O performance in the partitions where it occurs
210 the most. Now while I/O
211 performance in the larger partitions may be needed,
212 shifting them more toward the edge of the disk will not
213 lead to a significant performance improvement over moving
214 <filename>/var</filename> to the edge.
215 Finally, there are safety concerns. A smaller, neater root
216 partition which is mostly read-only has a greater
217 chance of surviving a bad crash.</para>
223 <sect1 id="configtuning-core-configuration">
224 <title>Core Configuration</title>
227 <primary>rc files</primary>
228 <secondary><filename>rc.conf</filename></secondary>
231 <para>The principal location for system configuration information
232 is within <filename>/etc/rc.conf</filename>. This file
233 contains a wide range of configuration information, principally
234 used at system startup to configure the system. Its name
235 directly implies this; it is configuration information for the
236 <filename>rc*</filename> files.</para>
238 <para>An administrator should make entries in the
239 <filename>rc.conf</filename> file to
240 override the default settings from
241 <filename>/etc/defaults/rc.conf</filename>. The defaults file
242 should not be copied verbatim to <filename>/etc</filename> - it
243 contains default values, not examples. All system-specific
244 changes should be made in the <filename>rc.conf</filename>
247 <para>A number of strategies may be applied in clustered
248 applications to separate site-wide configuration from
249 system-specific configuration in order to keep administration
250 overhead down. The recommended approach is to place site-wide
251 configuration into another file,
252 such as <filename>/etc/rc.conf.site</filename>, and then include
253 this file into <filename>/etc/rc.conf</filename>, which will
254 contain only system-specific information.</para>
256 <para>As <filename>rc.conf</filename> is read by &man.sh.1; it is
257 trivial to achieve this. For example:</para>
260 <listitem><para>rc.conf:</para>
261 <programlisting> . rc.conf.site
262 hostname="node15.example.com"
263 network_interfaces="fxp0 lo0"
264 ifconfig_fxp0="inet 10.1.1.1"</programlisting></listitem>
265 <listitem><para>rc.conf.site:</para>
266 <programlisting> defaultrouter="10.1.1.254"
268 blanktime="100"</programlisting></listitem>
271 <para>The <filename>rc.conf.site</filename> file can then be
272 distributed to every system using <command>rsync</command> or a
273 similar program, while the <filename>rc.conf</filename> file
274 remains unique.</para>
276 <para>Upgrading the system using
277 <command>make world</command> will not overwrite the
278 <filename>rc.conf</filename>
279 file, so system configuration information will not be lost.</para>
283 <sect1 id="configtuning-appconfig">
284 <title>Application Configuration</title>
286 <para>Typically, installed applications have their own
287 configuration files, with their own syntax, etc. It is
288 important that these files be kept separate from the base
289 system, so that they may be easily located and managed by the
290 package management tools.</para>
292 <indexterm><primary>/usr/local/etc</primary></indexterm>
294 <para>Typically, these files are installed in
295 <filename>/usr/local/etc</filename>. In the case where an
296 application has a large number of configuration files, a
297 subdirectory will be created to hold them.</para>
299 <para>Normally, when a port or package is installed, sample
300 configuration files are also installed. These are usually
301 identified with a <filename>.default</filename> suffix. If there
303 configuration files for the application, they will be created by
304 copying the <filename>.default</filename> files.</para>
306 <para>For example, consider the contents of the directory
307 <filename>/usr/local/etc/apache</filename>:</para>
309 <literallayout class="monospaced">-rw-r--r-- 1 root wheel 2184 May 20 1998 access.conf
310 -rw-r--r-- 1 root wheel 2184 May 20 1998 access.conf.default
311 -rw-r--r-- 1 root wheel 9555 May 20 1998 httpd.conf
312 -rw-r--r-- 1 root wheel 9555 May 20 1998 httpd.conf.default
313 -rw-r--r-- 1 root wheel 12205 May 20 1998 magic
314 -rw-r--r-- 1 root wheel 12205 May 20 1998 magic.default
315 -rw-r--r-- 1 root wheel 2700 May 20 1998 mime.types
316 -rw-r--r-- 1 root wheel 2700 May 20 1998 mime.types.default
317 -rw-r--r-- 1 root wheel 7980 May 20 1998 srm.conf
318 -rw-r--r-- 1 root wheel 7933 May 20 1998 srm.conf.default</literallayout>
320 <para>The file sizes show that only the <filename>srm.conf</filename>
321 file has been changed. A later update of the <application>Apache</application> port would not
322 overwrite this changed file.</para>
326 <sect1 id="configtuning-starting-services">
327 <title>Starting Services</title>
329 <indexterm><primary>services</primary></indexterm>
331 <para>It is common for a system to host a number of services.
332 These may be started in several different fashions, each having
333 different advantages.</para>
335 <indexterm><primary>/usr/local/etc/rc.d</primary></indexterm>
337 <para>Software installed from a port or the packages collection
338 will often place a script in
339 <filename>/usr/local/etc/rc.d</filename> which is invoked at
340 system startup with a <option>start</option> argument, and at
341 system shutdown with a <option>stop</option> argument.
342 This is the recommended way for
343 starting system-wide services that are to be run as
344 <username>root</username>, or that
345 expect to be started as <username>root</username>.
346 These scripts are registered as
347 part of the installation of the package, and will be removed
348 when the package is removed.</para>
350 <para>A generic startup script in
351 <filename>/usr/local/etc/rc.d</filename> looks like:</para>
353 <programlisting>#!/bin/sh
358 /usr/local/bin/foobar
361 kill -9 `cat /var/run/foobar.pid`
364 echo "Usage: `basename $0` {start|stop}" >&2
372 <para>The startup scripts of &os; will look in
373 <filename>/usr/local/etc/rc.d</filename> for scripts that have an
374 <literal>.sh</literal> extension and are executable by
375 <username>root</username>. Those scripts that are found are called with
376 an option <option>start</option> at startup, and <option>stop</option>
377 at shutdown to allow them to carry out their purpose. So if you wanted
378 the above sample script to be picked up and run at the proper time during
379 system startup, you should save it to a file called
380 <filename>FooBar.sh</filename> in
381 <filename>/usr/local/etc/rc.d</filename> and make sure it is
382 executable. You can make a shell script executable with &man.chmod.1;
383 as shown below:</para>
385 <screen>&prompt.root; <userinput>chmod 755 <replaceable>FooBar.sh</replaceable></userinput></screen>
387 <para>Some services expect to be invoked by &man.inetd.8; when a
388 connection is received on a suitable port. This is common for
389 mail reader servers (POP and IMAP, etc.). These services are
390 enabled by editing the file <filename>/etc/inetd.conf</filename>.
391 See &man.inetd.8; for details on editing this file.</para>
393 <para>Some additional system services may not be covered by the
394 toggles in <filename>/etc/rc.conf</filename>. These are
395 traditionally enabled by placing the command(s) to invoke them
396 in <filename>/etc/rc.local</filename> (which does not exist by default).
397 Note that <filename>rc.local</filename> is
398 generally regarded as the location of last resort; if there is a
399 better place to start a service, do it there.</para>
401 <note><para>Do <emphasis>not</emphasis> place any commands in
402 <filename>/etc/rc.conf</filename>. To start daemons, or
403 run any commands at boot time, place a script in
404 <filename>/usr/local/etc/rc.d</filename> instead.</para>
407 <para>It is also possible to use the &man.cron.8; daemon to start
408 system services. This approach has a number of advantages, not
409 least being that because &man.cron.8; runs these processes as the
410 owner of the <command>crontab</command>, services may be started
411 and maintained by non-<username>root</username> users.</para>
413 <para>This takes advantage of a feature of &man.cron.8;: the
414 time specification may be replaced by <literal>@reboot</literal>,
416 cause the job to be run when &man.cron.8; is started shortly after
420 <sect1 id="configtuning-cron">
424 <firstname>Tom</firstname>
425 <surname>Rhodes</surname>
426 <contrib>Contributed by </contrib>
431 <title>Configuring the <command>cron</command> Utility</title>
433 <indexterm><primary>cron</primary>
434 <secondary>configuration</secondary></indexterm>
436 <para>One of the most useful utilities in &os; is &man.cron.8;. The
437 <command>cron</command> utility runs in the background and constantly
438 checks the <filename>/etc/crontab</filename> file. The <command>cron</command>
439 utility also checks the <filename>/var/cron/tabs</filename> directory, in
440 search of new <filename>crontab</filename> files. These
441 <filename>crontab</filename> files store information about specific
442 functions which <command>cron</command> is supposed to perform at
443 certain times.</para>
445 <para>The <command>cron</command> utility uses two different
446 types of configuration files, the system crontab and user crontabs. The
447 only difference between these two formats is the sixth field. In the
448 system crontab, the sixth field is the name of a user for the command
449 to run as. This gives the system crontab the ability to run commands
450 as any user. In a user crontab, the sixth field is the command to run,
451 and all commands run as the user who created the crontab; this is an
452 important security feature.</para>
455 <para>User crontabs allow individual users to schedule tasks without the
456 need for root privileges. Commands in a user's crontab run with the
457 permissions of the user who owns the crontab.</para>
459 <para>The <username>root</username> user can have a user crontab just like
460 any other user. This one is different from
461 <filename>/etc/crontab</filename> (the system crontab). Because of the
462 system crontab, there's usually no need to create a user crontab
463 for <username>root</username>.</para>
466 <para>Let us take a look at the <filename>/etc/crontab</filename> file
467 (the system crontab):</para>
470 <!-- todo: add up-to-date crontab -->
471 <programlisting># /etc/crontab - root's crontab for &os;
473 # $&os;: src/etc/crontab,v 1.32 2002/11/22 16:13:39 tom Exp $
474 # <co id="co-comments">
477 PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin <co id="co-env">
481 #minute hour mday month wday who command <co id="co-field-descr">
484 */5 * * * * root /usr/libexec/atrun <co id="co-main">
488 <callout arearefs="co-comments">
489 <para>Like most &os; configuration files, the <literal>#</literal>
490 character represents a comment. A comment can be placed in
491 the file as a reminder of what and why a desired action is performed.
492 Comments cannot be on the same line as a command or else they will
493 be interpreted as part of the command; they must be on a new line.
494 Blank lines are ignored.</para>
497 <callout arearefs="co-env">
498 <para>First, the environment must be defined. The equals
499 (<literal>=</literal>) character is used to define any environment
500 settings, as with this example where it is used for the <envar>SHELL</envar>,
501 <envar>PATH</envar>, and <envar>HOME</envar> options. If the shell line is
502 omitted, <command>cron</command> will use the default, which is
503 <command>sh</command>. If the <envar>PATH</envar> variable is
504 omitted, no default will be used and file locations will need to
505 be absolute. If <envar>HOME</envar> is omitted, <command>cron</command>
506 will use the invoking users home directory.</para>
509 <callout arearefs="co-field-descr">
510 <para>This line defines a total of seven fields. Listed here are the
511 values <literal>minute</literal>, <literal>hour</literal>,
512 <literal>mday</literal>, <literal>month</literal>, <literal>wday</literal>,
513 <literal>who</literal>, and <literal>command</literal>. These
514 are almost all self explanatory. <literal>minute</literal> is the time in minutes the
515 command will be run. <literal>hour</literal> is similar to the <literal>minute</literal> option, just in
516 hours. <literal>mday</literal> stands for day of the month. <literal>month</literal> is similar to <literal>hour</literal>
517 and <literal>minute</literal>, as it designates the month. The <literal>wday</literal> option stands for
518 day of the week. All these fields must be numeric values, and follow
519 the twenty-four hour clock. The <literal>who</literal> field is special,
520 and only exists in the <filename>/etc/crontab</filename> file.
521 This field specifies which user the command should be run as.
522 When a user installs his or her <filename>crontab</filename> file, they
523 will not have this option. Finally, the <literal>command</literal> option is listed.
524 This is the last field, so naturally it should designate the command
525 to be executed.</para>
528 <callout arearefs="co-main">
529 <para>This last line will define the values discussed above. Notice here
530 we have a <literal>*/5</literal> listing, followed by several more
531 <literal>*</literal> characters. These <literal>*</literal> characters
532 mean <quote>first-last</quote>, and can be interpreted as
533 <emphasis>every</emphasis> time. So, judging by this line,
534 it is apparent that the <command>atrun</command> command is to be invoked by
535 <username>root</username> every five minutes regardless of what
536 day or month it is. For more information on the <command>atrun</command> command,
537 see the &man.atrun.8; manual page.</para>
539 <para>Commands can have any number of flags passed to them; however,
540 commands which extend to multiple lines need to be broken with the backslash
541 <quote>\</quote> continuation character.</para>
545 <para>This is the basic set up for every
546 <filename>crontab</filename> file, although there is one thing
547 different about this one. Field number six, where we specified
548 the username, only exists in the system
549 <filename>/etc/crontab</filename> file. This field should be
550 omitted for individual user <filename>crontab</filename>
554 <sect2 id="configtuning-installcrontab">
555 <title>Installing a Crontab</title>
558 <para>You must not use the procedure described here to
559 edit/install the system crontab. Simply use your favorite
560 editor: the <command>cron</command> utility will notice that the file
561 has changed and immediately begin using the updated version.
562 If you use <command>crontab</command> to load the
563 <filename>/etc/crontab</filename> file you may get an error
564 like <errorname>root: not found</errorname> because of the
565 system crontab's additional user field.</para>
568 <para>To install a freshly written user
569 <filename>crontab</filename>, first use your favorite editor to create
570 a file in the proper format, and then use the
571 <command>crontab</command> utility. The most common usage
574 <screen>&prompt.user; <userinput>crontab crontab-file</userinput></screen>
576 <para>In this example, <filename>crontab-file</filename> is the filename
577 of a <filename>crontab</filename> that was previously created.</para>
579 <para>There is also an option to list installed
580 <filename>crontab</filename> files: just pass the
581 <option>-l</option> option to <command>crontab</command> and look
582 over the output.</para>
584 <para>For users who wish to begin their own crontab file from scratch,
585 without the use of a template, the <command>crontab -e</command>
586 option is available. This will invoke the selected editor
587 with an empty file. When the file is saved, it will be
588 automatically installed by the <command>crontab</command> command.
591 <para>If you later want to remove your user <filename>crontab</filename>
592 completely, use <command>crontab</command> with the <option>-r</option>
599 <sect1 id="configtuning-rcNG">
603 <firstname>Tom</firstname>
604 <surname>Rhodes</surname>
605 <contrib>Contributed by </contrib>
611 <title>Using rc under &os;</title>
613 <indexterm><primary>rcNG</primary></indexterm>
615 <para>&os; uses the &netbsd;
616 <filename>rc.d</filename> system for system initialization.
617 Users should notice the files listed in the
618 <filename>/etc/rc.d</filename> directory. Many of these files
619 are for basic services which can be controlled with the
620 <option>start</option>, <option>stop</option>,
621 and <option>restart</option> options.
622 For instance, &man.sshd.8; can be restarted with the following
625 <screen>&prompt.root; <userinput>/etc/rc.d/sshd restart</userinput></screen>
627 <para>This procedure is similar for other services. Of course,
628 services are usually started automatically as specified in
629 &man.rc.conf.5;. For example, enabling the Network Address
630 Translation daemon at startup is as simple as adding the
631 following line to <filename>/etc/rc.conf</filename>:</para>
633 <programlisting>natd_enable="YES"</programlisting>
635 <para>If a <option>natd_enable="NO"</option> line is already
636 present, then simply change the <option>NO</option> to
637 <option>YES</option>. The rc scripts will automatically load
638 any other dependent services during the next reboot, as
639 described below.</para>
641 <para>Since the <filename>rc.d</filename> system is primarily
642 intended to start/stop services at system startup/shutdown time,
643 the standard <option>start</option>,
644 <option>stop</option> and <option>restart</option> options will only
645 perform their action if the appropriate
646 <filename>/etc/rc.conf</filename> variables are set. For
647 instance the above <command>sshd restart</command> command will
648 only work if <varname>sshd_enable</varname> is set to
649 <option>YES</option> in <filename>/etc/rc.conf</filename>. To
650 <option>start</option>, <option>stop</option> or
651 <option>restart</option> a service regardless of the settings in
652 <filename>/etc/rc.conf</filename>, the commands should be
653 prefixed with <quote>force</quote>. For instance to restart
654 <command>sshd</command> regardless of the current
655 <filename>/etc/rc.conf</filename> setting, execute the following
658 <screen>&prompt.root; <userinput>/etc/rc.d/sshd forcerestart</userinput></screen>
660 <para>It is easy to check if a service is enabled in
661 <filename>/etc/rc.conf</filename> by running the appropriate
662 <filename>rc.d</filename> script with the option
663 <option>rcvar</option>. Thus, an administrator can check that
664 <command>sshd</command> is in fact enabled in
665 <filename>/etc/rc.conf</filename> by running:</para>
667 <screen>&prompt.root; <userinput>/etc/rc.d/sshd rcvar</userinput>
669 $sshd_enable=YES</screen>
672 <para>The second line (<literal># sshd</literal>) is the output
673 from the <command>rc.d</command> script, not a
674 <username>root</username> prompt.</para>
677 <para>To determine if a service is running, a
678 <option>status</option> option is available. For instance to
679 verify that <command>sshd</command> is actually started:</para>
681 <screen>&prompt.root; <userinput>/etc/rc.d/sshd status</userinput>
682 sshd is running as pid 433.</screen>
684 <para>It is also possible to <option>reload</option> a service.
685 This will attempt to send a signal to an individual service, forcing the
686 service to reload its configuration files. In most cases this
687 means sending the service a <literal>SIGHUP</literal>
690 <para>The <application>rcNG</application> structure is used both
691 for network services and system initialization. Some services are run
692 only at boot; and the RCNG system is what triggers them.
694 <para>Many system services depend on other services to function
695 properly. For example, NIS and other RPC-based services may
696 fail to start until after the <command>rpcbind</command>
697 (portmapper) service has started. To resolve this issue,
698 information about dependencies and other meta-data is included
699 in the comments at the top of each startup script. The
700 &man.rcorder.8; program is then used to parse these comments
701 during system initialization to determine the order in which
702 system services should be invoked to satisfy the dependencies.
703 The following words may be included at the top of each startup
708 <para><literal>PROVIDE</literal>: Specifies the services this file provides.</para>
712 <para><literal>REQUIRE</literal>: Lists services which are required for this
713 service. This file will run <emphasis>after</emphasis>
714 the specified services.</para>
718 <para><literal>BEFORE</literal>: Lists services which depend on this service.
719 This file will run <emphasis>before</emphasis>
720 the specified services.</para>
724 <para>KEYWORD: When &man.rcorder.8; uses the <option>-k</option>
725 option, then only the rc.d files matching this keyword are used.
728 <para>Previously this was used to define *BSD dependent features.
731 For example, when using <option>-k shutdown</option>, only the
732 <filename>rc.d</filename> scripts defining the
733 <literal>shutdown</literal> keyword are used.
736 <para>With the <option>-s</option> option, &man.rcorder.8 will
737 skip any <filename>rc.d</filename> script defining the
738 corresponding keyword to skip. For example, scripts defining the
739 <literal>nostart</literal> keyword are skipped at boot time.</para>
743 <para>By using this method, an administrator can easily control system
744 services without the hassle of <quote>runlevels</quote> like
745 some other &unix; operating systems.</para>
747 <para>Additional information about the &os;
748 <filename>rc.d</filename> system can be found in the &man.rc.8;,
749 &man.rc.conf.5;, and &man.rc.subr.8; manual pages.</para>
752 <sect1 id="config-network-setup">
756 <firstname>Marc</firstname>
757 <surname>Fonvieille</surname>
758 <contrib>Contributed by </contrib>
759 <!-- 6 October 2002 -->
764 <title>Setting Up Network Interface Cards</title>
766 <indexterm><primary>network card configuration</primary></indexterm>
768 <para>Nowadays we can not think about a computer without thinking
769 about a network connection. Adding and configuring a network
770 card is a common task for any &os; administrator.</para>
773 <title>Locating the Correct Driver</title>
776 <primary>network card configuration</primary>
777 <secondary>locating the driver</secondary>
780 <para>Before you begin, you should know the model of the card
781 you have, the chip it uses, and whether it is a PCI or ISA card.
782 &os; supports a wide variety of both PCI and ISA cards.
783 Check the Hardware Compatibility List for your release to see
784 if your card is supported.</para>
786 <para>Once you are sure your card is supported, you need
787 to determine the proper driver for the card. The file
788 <filename>/usr/src/sys/i386/conf/LINT</filename> will give you
789 the list of network interfaces drivers with some information
790 about the supported chipsets/cards. If you have doubts about
791 which driver is the correct one, read the manual page of the
792 driver. The manual page will give you more information about
793 the supported hardware and even the possible problems that
796 <para>If you own a common card, most of the time you will not
797 have to look very hard for a driver. Drivers for common
798 network cards are present in the <filename>GENERIC</filename>
799 kernel, so your card should show up during boot, like so:</para>
801 <screen>dc0: <82c169 PNIC 10/100BaseTX> port 0xa000-0xa0ff mem 0xd3800000-0xd38
802 000ff irq 15 at device 11.0 on pci0
803 dc0: Ethernet address: 00:a0:cc:da:da:da
804 miibus0: <MII bus> on dc0
805 ukphy0: <Generic IEEE 802.3u media interface> on miibus0
806 ukphy0: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto
807 dc1: <82c169 PNIC 10/100BaseTX> port 0x9800-0x98ff mem 0xd3000000-0xd30
808 000ff irq 11 at device 12.0 on pci0
809 dc1: Ethernet address: 00:a0:cc:da:da:db
810 miibus1: <MII bus> on dc1
811 ukphy1: <Generic IEEE 802.3u media interface> on miibus1
812 ukphy1: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto</screen>
814 <para>In this example, we see that two cards using the &man.dc.4;
815 driver are present on the system.</para>
817 <para>To use your network card, you will need to load the proper
818 driver. This may be accomplished in one of two ways. The
819 easiest way is to simply load a kernel module for your network
820 card with &man.kldload.8;. A module is not available for all
821 network card drivers (ISA cards and cards using the &man.ed.4;
822 driver, for example). Alternatively, you may statically compile
823 the support for your card into your kernel. Check
824 <filename>/usr/src/sys/i386/conf/LINT</filename> and the
825 manual page of the driver to know what to add in your kernel
826 configuration file. For more information about recompiling your
827 kernel, please see <xref linkend="kernelconfig">. If your card
828 was detected at boot by your kernel (<filename>GENERIC</filename>)
829 you do not have to build a new kernel.</para>
833 <title>Configuring the Network Card</title>
836 <primary>Network card configuration</primary>
837 <secondary>configuration</secondary>
840 <para>Once the right driver is loaded for the network card, the
841 card needs to be configured. As with many other things, the
842 network card may have been configured at installation time.</para>
844 <para>To display the configuration for the network interfaces on
845 your system, enter the following command:</para>
847 <screen>&prompt.user; <userinput>ifconfig</userinput>
848 dc0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
849 inet 192.168.1.3 netmask 0xffffff00 broadcast 192.168.1.255
850 ether 00:a0:cc:da:da:da
851 media: Ethernet autoselect (100baseTX <full-duplex>)
853 dc1: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
854 inet 10.0.0.1 netmask 0xffffff00 broadcast 10.0.0.255
855 ether 00:a0:cc:da:da:db
856 media: Ethernet 10baseT/UTP
858 lp0: flags=8810<POINTOPOINT,SIMPLEX,MULTICAST> mtu 1500
859 lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> mtu 16384
860 inet 127.0.0.1 netmask 0xff000000
861 tun0: flags=8010<POINTOPOINT,MULTICAST> mtu 1500</screen>
864 <para>Note that entries concerning IPv6
865 (<literal>inet6</literal> etc.) were omitted in this
869 <para>In this example, the following devices were
874 <para><devicename>dc0</devicename>: The first Ethernet
879 <para><devicename>dc1</devicename>: The second Ethernet
884 <para><devicename>lp0</devicename>: The parallel port
889 <para><devicename>lo0</devicename>: The loopback device</para>
893 <para><devicename>tun0</devicename>: The tunnel device used by
894 <application>ppp</application></para>
898 <para>&os; uses the driver name followed by the order in
899 which one the card is detected at the kernel boot to name the
900 network card, starting the count at zero. For example,
901 <devicename>sis2</devicename> would be the third network card
902 on the system using the &man.sis.4; driver.</para>
904 <para>In this example, the <devicename>dc0</devicename> device is
905 up and running. The key indicators are:</para>
909 <para><literal>UP</literal> means that the card is configured
914 <para>The card has an Internet (<literal>inet</literal>)
915 address (in this case
916 <hostid role="ipaddr">192.168.1.3</hostid>).</para>
920 <para>It has a valid subnet mask (<literal>netmask</literal>;
921 <hostid role="netmask">0xffffff00</hostid> is the same as
922 <hostid role="netmask">255.255.255.0</hostid>).</para>
926 <para>It has a valid broadcast address (in this case,
927 <hostid role="ipaddr">192.168.1.255</hostid>).</para>
931 <para>The MAC address of the card (<literal>ether</literal>)
932 is <hostid role="mac">00:a0:cc:da:da:da</hostid></para>
936 <para>The physical media selection is on autoselection mode
937 (<literal>media: Ethernet autoselect (100baseTX
938 <full-duplex>)</literal>). We see that
939 <devicename>dc1</devicename> was configured to run with
940 <literal>10baseT/UTP</literal> media. For more
941 information on available media types for a driver, please
942 refer to its manual page.</para>
946 <para>The status of the link (<literal>status</literal>)
947 is <literal>active</literal>, i.e. the carrier is detected.
948 For <devicename>dc1</devicename>, we see
949 <literal>status: no carrier</literal>. This is normal when
950 an Ethernet cable is not plugged into the card.</para>
954 <para>If the &man.ifconfig.8; output had shown something similar
957 <screen>dc0: flags=8843<BROADCAST,SIMPLEX,MULTICAST> mtu 1500
958 ether 00:a0:cc:da:da:da</screen>
960 <para>it would indicate the card has not been configured.</para>
962 <para>To configure your card, you need <username>root</username>
963 privileges. The network card configuration can be done from the
964 command line with &man.ifconfig.8; as root.</para>
967 &prompt.root; <userinput>ifconfig dc0 inet 192.168.1.3 netmask 255.255.255.0</userinput>
971 <para>Manually configuring the care has the disadvantage that you
972 would have to do it after each reboot of the system. The file
973 <filename>/etc/rc.conf</filename> is where to add the network
974 card's configuration.</para>
976 <para>Open <filename>/etc/rc.conf</filename> in your favorite
977 editor. You need to add a line for each network card present on
978 the system, for example in our case, we added these lines:</para>
980 <programlisting>ifconfig_dc0="inet 192.168.1.3 netmask 255.255.255.0"
981 ifconfig_dc1="inet 10.0.0.1 netmask 255.255.255.0 media 10baseT/UTP"</programlisting>
983 <para>You have to replace <devicename>dc0</devicename>,
984 <devicename>dc1</devicename>, and so on, with
985 the correct device for your cards, and the addresses with the
986 proper ones. You should read the card driver and
987 &man.ifconfig.8; manual pages for more details about the allowed
988 options and also &man.rc.conf.5; manual page for more
989 information on the syntax of
990 <filename>/etc/rc.conf</filename>.</para>
992 <para>If you configured the network during installation, some
993 lines about the network card(s) may be already present. Double
994 check <filename>/etc/rc.conf</filename> before adding any
997 <para>You will also have to edit the file
998 <filename>/etc/hosts</filename> to add the names and the IP
999 addresses of various machines of the LAN, if they are not already
1000 there. For more information please refer to &man.hosts.5;
1001 and to <filename>/usr/share/examples/etc/hosts</filename>.</para>
1005 <title>Testing and Troubleshooting</title>
1007 <para>Once you have made the necessary changes in
1008 <filename>/etc/rc.conf</filename>, you should reboot your
1009 system. This will allow the change(s) to the interface(s) to
1010 be applied, and verify that the system restarts without any
1011 configuration errors.</para>
1013 <para>Once the system has been rebooted, you should test the
1014 network interfaces.</para>
1017 <title>Testing the Ethernet Card</title>
1020 <primary>network card configuration</primary>
1021 <secondary>testing the card</secondary>
1024 <para>To verify that an Ethernet card is configured correctly,
1025 you have to try two things. First, ping the interface itself,
1026 and then ping another machine on the LAN.</para>
1028 <para>First test the local interface:</para>
1030 <screen>&prompt.user; <userinput>ping -c5 192.168.1.3</userinput>
1031 PING 192.168.1.3 (192.168.1.3): 56 data bytes
1032 64 bytes from 192.168.1.3: icmp_seq=0 ttl=64 time=0.082 ms
1033 64 bytes from 192.168.1.3: icmp_seq=1 ttl=64 time=0.074 ms
1034 64 bytes from 192.168.1.3: icmp_seq=2 ttl=64 time=0.076 ms
1035 64 bytes from 192.168.1.3: icmp_seq=3 ttl=64 time=0.108 ms
1036 64 bytes from 192.168.1.3: icmp_seq=4 ttl=64 time=0.076 ms
1038 --- 192.168.1.3 ping statistics ---
1039 5 packets transmitted, 5 packets received, 0% packet loss
1040 round-trip min/avg/max/stddev = 0.074/0.083/0.108/0.013 ms</screen>
1042 <para>Now we have to ping another machine on the LAN:</para>
1044 <screen>&prompt.user; <userinput>ping -c5 192.168.1.2</userinput>
1045 PING 192.168.1.2 (192.168.1.2): 56 data bytes
1046 64 bytes from 192.168.1.2: icmp_seq=0 ttl=64 time=0.726 ms
1047 64 bytes from 192.168.1.2: icmp_seq=1 ttl=64 time=0.766 ms
1048 64 bytes from 192.168.1.2: icmp_seq=2 ttl=64 time=0.700 ms
1049 64 bytes from 192.168.1.2: icmp_seq=3 ttl=64 time=0.747 ms
1050 64 bytes from 192.168.1.2: icmp_seq=4 ttl=64 time=0.704 ms
1052 --- 192.168.1.2 ping statistics ---
1053 5 packets transmitted, 5 packets received, 0% packet loss
1054 round-trip min/avg/max/stddev = 0.700/0.729/0.766/0.025 ms</screen>
1056 <para>You could also use the machine name instead of
1057 <hostid role="ipaddr">192.168.1.2</hostid> if you have set up the
1058 <filename>/etc/hosts</filename> file.</para>
1062 <title>Troubleshooting</title>
1065 <primary>network card configuration</primary>
1066 <secondary>troubleshooting</secondary>
1069 <para>Troubleshooting hardware and software configurations is always
1070 a pain, and a pain which can be alleviated by checking the simple
1071 things first. Is your network cable plugged in? Have you properly
1072 configured the network services? Did you configure the firewall
1073 correctly? Is the card you are using supported by &os;? Always
1074 check the hardware notes before sending off a bug report. Update
1075 your version of &os; to the latest PREVIEW version. Check the
1076 mailing list archives, or perhaps search the Internet.</para>
1078 <para>If the card works, yet performance is poor, it would be
1079 worthwhile to read over the &man.tuning.7; manual page. You
1080 can also check the network configuration as incorrect network
1081 settings can cause slow connections.</para>
1083 <para>Some users experience one or two <quote>device
1084 timeouts</quote>, which is normal for some cards. If they
1085 continue, or are bothersome, you may wish to be sure the
1086 device is not conflicting with another device. Double check
1087 the cable connections. Perhaps you may just need to get
1088 another card.</para>
1090 <para>At times, users see a few <errorname>watchdog timeout</errorname>
1091 errors. The first thing to do here is to check your network
1092 cable. Many cards require a PCI slot which supports Bus
1093 Mastering. On some old motherboards, only one PCI slot allows
1094 it (usually slot 0). Check the network card and the
1095 motherboard documentation to determine if that may be the
1098 <para><errorname>No route to host</errorname> messages occur if the
1099 system is unable to route a packet to the destination host.
1100 This can happen if no default route is specified, or if a
1101 cable is unplugged. Check the output of <command>netstat
1102 -rn</command> and make sure there is a valid route to the host
1103 you are trying to reach. If there is not, read on to <xref
1104 linkend="advanced-networking">.</para>
1106 <para><errorname>ping: sendto: Permission denied</errorname> error
1107 messages are often caused by a misconfigured firewall. If
1108 <command>ipfw</command> is enabled in the kernel but no rules
1109 have been defined, then the default policy is to deny all
1110 traffic, even ping requests! Read on to <xref
1111 linkend="firewalls"> for more information.</para>
1113 <para>Sometimes performance of the card is poor, or below average.
1114 In these cases it is best to set the media selection mode
1115 from <literal>autoselect</literal> to the correct media selection.
1116 While this usually works for most hardware, it may not resolve
1117 this issue for everyone. Again, check all the network settings,
1118 and read over the &man.tuning.7; manual page.</para>
1124 <sect1 id="configtuning-virtual-hosts">
1125 <title>Virtual Hosts</title>
1127 <indexterm><primary>virtual hosts</primary></indexterm>
1128 <indexterm><primary>IP aliases</primary></indexterm>
1130 <para>A very common use of &os; is virtual site hosting, where
1131 one server appears to the network as many servers. This is
1132 achieved by assigning multiple network addresses to a single
1135 <para>A given network interface has one <quote>real</quote> address,
1136 and may have any number of <quote>alias</quote> addresses.
1138 normally added by placing alias entries in
1139 <filename>/etc/rc.conf</filename>.</para>
1141 <para>An alias entry for the interface <devicename>fxp0</devicename>
1144 <programlisting>ifconfig_fxp0_alias0="inet xxx.xxx.xxx.xxx netmask xxx.xxx.xxx.xxx"</programlisting>
1146 <para>Note that alias entries must start with
1147 <literal>alias0</literal> and proceed upwards in order, (for example,
1148 <literal>_alias1</literal>, <literal>_alias2</literal>, and so on).
1149 The configuration process will stop at the first missing number.
1152 <para>The calculation of alias netmasks is important, but
1153 fortunately quite simple. For a given interface, there must be
1154 one address which correctly represents the network's netmask.
1155 Any other addresses which fall within this network must have a
1156 netmask of all <literal>1</literal>s (expressed as either
1157 <hostid role="netmask">255.255.255.255</hostid> or
1158 <hostid role="netmask">0xffffffff</hostid>).
1161 <para>For example, consider the case where the
1162 <devicename>fxp0</devicename> interface is
1163 connected to two networks, the <hostid role="ipaddr">10.1.1.0</hostid>
1164 network with a netmask of <hostid role="netmask">255.255.255.0</hostid>
1165 and the <hostid role="ipaddr">202.0.75.16</hostid> network with
1166 a netmask of <hostid role="netmask">255.255.255.240</hostid>.
1167 We want the system to appear at <hostid role="ipaddr">10.1.1.1</hostid>
1168 through <hostid role="ipaddr">10.1.1.5</hostid> and at
1169 <hostid role="ipaddr">202.0.75.17</hostid> through
1170 <hostid role="ipaddr">202.0.75.20</hostid>. As noted above, only the
1171 first address in a given network range (in this case,
1172 <hostid role="ipaddr">10.0.1.1</hostid> and
1173 <hostid role="ipaddr">202.0.75.17</hostid>) should have a real
1174 netmask; all the rest (<hostid role="ipaddr">10.1.1.2</hostid>
1175 through <hostid role="ipaddr">10.1.1.5</hostid> and
1176 <hostid role="ipaddr">202.0.75.18</hostid> through
1177 <hostid role="ipaddr">202.0.75.20</hostid>) must be configured with a
1178 netmask of <hostid role="netmask">255.255.255.255</hostid>.</para>
1180 <para>The following entries configure the adapter correctly for
1181 this arrangement:</para>
1183 <programlisting> ifconfig_fxp0="inet 10.1.1.1 netmask 255.255.255.0"
1184 ifconfig_fxp0_alias0="inet 10.1.1.2 netmask 255.255.255.255"
1185 ifconfig_fxp0_alias1="inet 10.1.1.3 netmask 255.255.255.255"
1186 ifconfig_fxp0_alias2="inet 10.1.1.4 netmask 255.255.255.255"
1187 ifconfig_fxp0_alias3="inet 10.1.1.5 netmask 255.255.255.255"
1188 ifconfig_fxp0_alias4="inet 202.0.75.17 netmask 255.255.255.240"
1189 ifconfig_fxp0_alias5="inet 202.0.75.18 netmask 255.255.255.255"
1190 ifconfig_fxp0_alias6="inet 202.0.75.19 netmask 255.255.255.255"
1191 ifconfig_fxp0_alias7="inet 202.0.75.20 netmask 255.255.255.255"</programlisting>
1195 <sect1 id="configtuning-configfiles">
1196 <title>Configuration Files</title>
1199 <title><filename>/etc</filename> Layout</title>
1200 <para>There are a number of directories in which configuration
1201 information is kept. These include:</para>
1203 <informaltable frame="none">
1205 <colspec colwidth="1*">
1206 <colspec colwidth="2*">
1209 <entry><filename>/etc</filename></entry>
1210 <entry>Generic system configuration information; data here is
1211 system-specific.</entry>
1214 <entry><filename>/etc/defaults</filename></entry>
1215 <entry>Default versions of system configuration files.</entry>
1218 <entry><filename>/etc/mail</filename></entry>
1219 <entry>Extra &man.sendmail.8; configuration, other
1220 MTA configuration files.
1224 <entry><filename>/etc/ppp</filename></entry>
1225 <entry>Configuration for both user- and kernel-ppp programs.
1229 <entry><filename>/etc/namedb</filename></entry>
1230 <entry>Default location for &man.named.8; data. Normally
1231 <filename>named.conf</filename> and zone files are stored
1235 <entry><filename>/usr/local/etc</filename></entry>
1236 <entry>Configuration files for installed applications.
1237 May contain per-application subdirectories.</entry>
1240 <entry><filename>/usr/local/etc/rc.d</filename></entry>
1241 <entry>Start/stop scripts for installed applications.</entry>
1244 <entry><filename>/var/db</filename></entry>
1245 <entry>Automatically generated system-specific database files,
1246 such as the package database, the locate database, and so
1255 <title>Hostnames</title>
1257 <indexterm><primary>hostname</primary></indexterm>
1258 <indexterm><primary>DNS</primary></indexterm>
1261 <title><filename>/etc/resolv.conf</filename></title>
1264 <primary><filename>resolv.conf</filename></primary>
1267 <para><filename>/etc/resolv.conf</filename> dictates how &os;'s
1268 resolver accesses the Internet Domain Name System (DNS).</para>
1270 <para>The most common entries to <filename>resolv.conf</filename> are:
1273 <informaltable frame="none">
1275 <colspec colwidth="1*">
1276 <colspec colwidth="2*">
1279 <entry><literal>nameserver</literal></entry>
1280 <entry>The IP address of a name server the resolver
1281 should query. The servers are queried in the order
1282 listed with a maximum of three.</entry>
1285 <entry><literal>search</literal></entry>
1286 <entry>Search list for hostname lookup. This is normally
1287 determined by the domain of the local hostname.</entry>
1290 <entry><literal>domain</literal></entry>
1291 <entry>The local domain name.</entry>
1297 <para>A typical <filename>resolv.conf</filename>:</para>
1299 <programlisting>search example.com
1300 nameserver 147.11.1.11
1301 nameserver 147.11.100.30</programlisting>
1303 <note><para>Only one of the <literal>search</literal> and
1304 <literal>domain</literal> options should be used.</para></note>
1306 <para>If you are using DHCP, &man.dhclient.8; usually rewrites
1307 <filename>resolv.conf</filename> with information received from the
1312 <title><filename>/etc/hosts</filename></title>
1314 <indexterm><primary>hosts</primary></indexterm>
1316 <para><filename>/etc/hosts</filename> is a simple text
1317 database reminiscent of the old Internet. It works in
1318 conjunction with DNS and NIS providing name to IP address
1319 mappings. Local computers connected via a LAN can be placed
1320 in here for simplistic naming purposes instead of setting up
1321 a &man.named.8; server. Additionally,
1322 <filename>/etc/hosts</filename> can be used to provide a
1323 local record of Internet names, reducing the need to query
1324 externally for commonly accessed names.</para>
1326 <programlisting># $&os;$
1329 # This file should contain the addresses and aliases
1330 # for local hosts that share this file.
1331 # In the presence of the domain name service or NIS, this file may
1332 # not be consulted at all; see /etc/nsswitch.conf for the resolution order.
1335 ::1 localhost localhost.my.domain myname.my.domain
1336 127.0.0.1 localhost localhost.my.domain myname.my.domain
1339 # Imaginary network.
1340 #10.0.0.2 myname.my.domain myname
1341 #10.0.0.3 myfriend.my.domain myfriend
1343 # According to RFC 1918, you can use the following IP networks for
1344 # private nets which will never be connected to the Internet:
1346 # 10.0.0.0 - 10.255.255.255
1347 # 172.16.0.0 - 172.31.255.255
1348 # 192.168.0.0 - 192.168.255.255
1350 # In case you want to be able to connect to the Internet, you need
1351 # real official assigned numbers. PLEASE PLEASE PLEASE do not try
1352 # to invent your own network numbers but instead get one from your
1353 # network provider (if any) or from the Internet Registry (ftp to
1354 # rs.internic.net, directory `/templates').
1357 <para><filename>/etc/hosts</filename> takes on the simple format
1360 <programlisting>[Internet address] [official hostname] [alias1] [alias2] ...</programlisting>
1362 <para>For example:</para>
1364 <programlisting>10.0.0.1 myRealHostname.example.com myRealHostname foobar1 foobar2</programlisting>
1366 <para>Consult &man.hosts.5; for more information.</para>
1371 <title>Log File Configuration</title>
1373 <indexterm><primary>log files</primary></indexterm>
1376 <title><filename>syslog.conf</filename></title>
1378 <indexterm><primary>syslog.conf</primary></indexterm>
1380 <para><filename>syslog.conf</filename> is the configuration file
1381 for the &man.syslogd.8; program. It indicates which types
1382 of <command>syslog</command> messages are logged to particular
1385 <programlisting># $&os;$
1387 # Spaces ARE valid field separators in this file. However,
1388 # other *nix-like systems still insist on using tabs as field
1389 # separators. If you are sharing this file between systems, you
1390 # may want to use only tabs as field separators here.
1391 # Consult the syslog.conf(5) manual page.
1392 *.err;kern.debug;auth.notice;mail.crit /dev/console
1393 *.notice;kern.debug;lpr.info;mail.crit;news.err /var/log/messages
1394 security.* /var/log/security
1395 mail.info /var/log/maillog
1396 lpr.info /var/log/lpd-errs
1397 cron.* /var/log/cron
1399 *.notice;news.err root
1402 # uncomment this to log all writes to /dev/console to /var/log/console.log
1403 #console.info /var/log/console.log
1404 # uncomment this to enable logging of all log messages to /var/log/all.log
1405 #*.* /var/log/all.log
1406 # uncomment this to enable logging to a remote log host named loghost
1408 # uncomment these if you're running inn
1409 # news.crit /var/log/news/news.crit
1410 # news.err /var/log/news/news.err
1411 # news.notice /var/log/news/news.notice
1413 *.* /var/log/slip.log
1415 *.* /var/log/ppp.log</programlisting>
1417 <!-- todo: reed: this should be documented in book -->
1418 <para>Consult the &man.syslog.conf.5; manual page for more
1423 <title><filename>newsyslog.conf</filename></title>
1425 <indexterm><primary>newsyslog.conf</primary></indexterm>
1427 <para><filename>newsyslog.conf</filename> is the configuration
1428 file for &man.newsyslog.8;, a program that is normally scheduled
1429 to run by &man.cron.8;. &man.newsyslog.8; determines when log
1430 files require archiving or rearranging.
1431 <filename>logfile</filename> is moved to
1432 <filename>logfile.0</filename>, <filename>logfile.0</filename>
1433 is moved to <filename>logfile.1</filename>, and so on.
1434 Alternatively, the log files may be archived in &man.gzip.1; format
1435 causing them to be named: <filename>logfile.0.gz</filename>,
1436 <filename>logfile.1.gz</filename>, and so on.</para>
1438 <para><filename>newsyslog.conf</filename> indicates which log
1439 files are to be managed, how many are to be kept, and when
1440 they are to be touched. Log files can be rearranged and/or
1441 archived when they have either reached a certain size, or at a
1442 certain periodic time/date.</para>
1444 <programlisting># configuration file for newsyslog
1445 # $&os;$
1447 # filename [owner:group] mode count size when [ZB] [/pid_file] [sig_num]
1448 /var/log/cron 600 3 100 * Z
1449 /var/log/amd.log 644 7 100 * Z
1450 /var/log/kerberos.log 644 7 100 * Z
1451 /var/log/lpd-errs 644 7 100 * Z
1452 /var/log/maillog 644 7 * @T00 Z
1453 /var/log/sendmail.st 644 10 * 168 B
1454 /var/log/messages 644 5 100 * Z
1455 /var/log/all.log 600 7 * @T00 Z
1456 /var/log/slip.log 600 3 100 * Z
1457 /var/log/ppp.log 600 3 100 * Z
1458 /var/log/security 600 10 100 * Z
1459 /var/log/wtmp 644 3 * @01T05 B
1460 /var/log/daily.log 640 7 * @T00 Z
1461 /var/log/weekly.log 640 5 1 $W6D0 Z
1462 /var/log/monthly.log 640 12 * $M1D0 Z
1463 /var/log/console.log 640 5 100 * Z</programlisting>
1465 <!-- todo: reed: this should be documented in book -->
1466 <para>Consult the &man.newsyslog.8; manual page for more
1471 <sect2 id="configtuning-sysctlconf">
1472 <title><filename>sysctl.conf</filename></title>
1474 <indexterm><primary>sysctl.conf</primary></indexterm>
1475 <indexterm><primary>sysctl</primary></indexterm>
1477 <para><filename>sysctl.conf</filename> looks much like
1478 <filename>rc.conf</filename>. Values are set in a
1479 <literal>variable=value</literal>
1480 form. The specified values are set after the system goes into
1481 multi-user mode. Not all variables are settable in this mode.</para>
1483 <para>A sample <filename>sysctl.conf</filename> turning off logging
1484 of fatal signal exits and letting Linux programs know they are really
1485 running under &os;:</para>
1487 <programlisting>kern.logsigexit=0 # Do not log fatal signal exits (e.g. sig 11)
1488 compat.linux.osname=&os;
1489 <!-- todo: reed: check this -->
1490 compat.linux.osrelease=4.3-STABLE</programlisting>
1494 <sect1 id="configtuning-sysctl">
1495 <title>Tuning with sysctl</title>
1497 <indexterm><primary>sysctl</primary></indexterm>
1499 <primary>tuning</primary>
1500 <secondary>with sysctl</secondary>
1503 <para>&man.sysctl.8; is an interface that allows you to make changes
1504 to a running &os; system. This includes many advanced
1505 options of the TCP/IP stack and virtual memory system that can
1506 dramatically improve performance for an experienced system
1507 administrator. Over five hundred system variables can be read
1508 and set using &man.sysctl.8;.</para>
1510 <para>At its core, &man.sysctl.8; serves two functions: to read and
1511 to modify system settings.</para>
1513 <para>To view all readable variables:</para>
1515 <screen>&prompt.user; <userinput>sysctl -a</userinput></screen>
1517 <para>To read a particular variable, for example,
1518 <varname>kern.maxproc</varname>:</para>
1520 <screen>&prompt.user; <userinput>sysctl kern.maxproc</userinput>
1521 kern.maxproc: 1044</screen>
1523 <para>To set a particular variable, use the intuitive
1524 <replaceable>variable</replaceable>=<replaceable>value</replaceable>
1527 <screen>&prompt.root; <userinput>sysctl kern.maxfiles=5000</userinput>
1528 kern.maxfiles: 2088 -> 5000</screen>
1530 <para>Settings of sysctl variables are usually either strings,
1531 numbers, or booleans (a boolean being <literal>1</literal> for yes
1532 or a <literal>0</literal> for no).</para>
1534 <para>If you want to set automatically some variables each time
1535 the machine boots, add them to the
1536 <filename>/etc/sysctl.conf</filename> file. For more information
1537 see the &man.sysctl.conf.5; manual page and the
1538 <xref linkend="configtuning-sysctlconf">.</para>
1540 <sect2 id="sysctl-readonly">
1544 <firstname>Tom</firstname>
1545 <surname>Rhodes</surname>
1546 <contrib>Contributed by </contrib>
1547 <!-- 31 January 2003 -->
1551 <title>&man.sysctl.8; Read-only</title>
1553 <para>In some cases it may be desirable to modify read-only &man.sysctl.8;
1554 values. While this is not recommended, it is also sometimes unavoidable.</para>
1556 <para>For instance on some laptop models the &man.cardbus.4; device will
1557 not probe memory ranges, and fail with errors which look similar to:</para>
1559 <screen>cbb0: Could not map register memory
1560 device_probe_and_attach: cbb0 attach returned 12</screen>
1562 <para>Cases like the one above usually require the modification of some
1563 default &man.sysctl.8; settings which are set read only. To overcome
1564 these situations a user can put &man.sysctl.8; <quote>OIDs</quote>
1565 in their local <filename>/boot/loader.conf</filename>. Default
1566 settings are located in the <filename>/boot/defaults/loader.conf</filename>
1569 <para>Fixing the problem mentioned above would require a user to set
1570 <option>hw.pci.allow_unsupported_io_range=1</option> in the aforementioned
1571 file. Now &man.cardbus.4; will work properly.</para>
1576 <sect1 id="configtuning-disk">
1577 <title>Tuning Disks</title>
1580 <title>Sysctl Variables</title>
1583 <title><varname>vfs.vmiodirenable</varname></title>
1586 <primary><varname>vfs.vmiodirenable</varname></primary>
1589 <para>The <varname>vfs.vmiodirenable</varname> sysctl variable
1590 may be set to either 0 (off) or 1 (on); it is 1 by default.
1591 This variable controls how directories are cached by the
1592 system. Most directories are small, using just a single
1593 fragment (typically 1 K) in the file system and less
1594 (typically 512 bytes) in the buffer cache.
1595 With this variable turned off (to 0), the buffer
1596 cache will only cache a fixed number of directories even if
1597 ou have a huge amount of memory. When turned on (to 1), this sysctl
1598 allows the buffer cache to use the VM Page Cache to cache the
1599 directories, making all the memory available for caching
1600 directories. However,
1601 the minimum in-core memory used to cache a directory is the
1602 physical page size (typically 4 K) rather than 512
1603 bytes. We recommend keeping this option on if you are running
1604 any services which manipulate large numbers of files. Such
1605 services can include web caches, large mail systems, and news
1606 systems. Keeping this option on will generally not reduce
1607 performance even with the wasted memory but you should
1608 experiment to find out.</para>
1612 <title><varname>vfs.write_behind</varname></title>
1615 <primary><varname>vfs.write_behind</varname></primary>
1618 <para>The <varname>vfs.write_behind</varname> sysctl variable
1619 defaults to <literal>1</literal> (on). This tells the file system
1620 to issue media writes as full clusters are collected, which
1621 typically occurs when writing large sequential files. The idea
1622 is to avoid saturating the buffer cache with dirty buffers when
1623 it would not benefit I/O performance. However, this may stall
1624 processes and under certain circumstances you may wish to turn it
1629 <title><varname>vfs.hirunningspace</varname></title>
1632 <primary><varname>vfs.hirunningspace</varname></primary>
1635 <para>The <varname>vfs.hirunningspace</varname> sysctl variable
1636 determines how much outstanding write I/O may be queued to disk
1637 controllers system-wide at any given instance. The default is
1638 usually sufficient but on machines with lots of disks you may
1639 want to bump it up to four or five <emphasis>megabytes</emphasis>.
1640 Note that setting too high a value (exceeding the buffer cache's
1641 write threshold) can lead to extremely bad clustering
1642 performance. Do not set this value arbitrarily high! Higher
1643 write values may add latency to reads occurring at the same time.
1646 <para>There are various other buffer-cache and VM page cache
1647 related sysctls. We do not recommend modifying these values.
1648 The VM system does an extremely good job of
1649 automatically tuning itself.</para>
1653 <title><varname>vm.swap_idle_enabled</varname></title>
1656 <primary><varname>vm.swap_idle_enabled</varname></primary>
1659 <para>The <varname>vm.swap_idle_enabled</varname> sysctl variable
1660 is useful in large multi-user systems where you have lots of
1661 users entering and leaving the system and lots of idle processes.
1662 Such systems tend to generate a great deal of continuous pressure
1663 on free memory reserves. Turning this feature on and tweaking
1664 the swapout hysteresis (in idle seconds) via
1665 <varname>vm.swap_idle_threshold1</varname> and
1666 <varname>vm.swap_idle_threshold2</varname> allows you to depress
1667 the priority of memory pages associated with idle processes more
1668 quickly then the normal pageout algorithm. This gives a helping
1669 hand to the pageout daemon. Do not turn this option on unless
1670 you need it, because the tradeoff you are making is essentially
1671 pre-page memory sooner rather than later; thus eating more swap
1672 and disk bandwidth. In a small system this option will have a
1673 determinable effect but in a large system that is already doing
1674 moderate paging this option allows the VM system to stage whole
1675 processes into and out of memory easily.</para>
1679 <title><varname>hw.ata.wc</varname></title>
1682 <primary><varname>hw.ata.wc</varname></primary>
1685 <para>IDE drives lie about when a write completes. With IDE write
1686 caching turned on, IDE hard drives not only write data
1687 to disk out of order, but will sometimes delay writing some
1688 blocks indefinitely when under heavy disk loads. A crash or
1689 power failure may cause serious file system corruption. Turning
1690 off write caching will remove the danger of this data loss, but
1691 will also cause disk operations to proceed
1692 <emphasis>very slowly.</emphasis> Change this only if prepared
1693 to suffer with the disk slowdown.</para>
1695 <para>Changing this variable must be done from the
1696 boot loader at boot time. Attempting to do it after the
1697 kernel boots will have no effect.</para>
1699 <para>For more information, please see &man.ata.4; manual page.</para>
1704 <sect2 id="soft-updates">
1705 <title>Soft Updates</title>
1707 <indexterm><primary>Soft Updates</primary></indexterm>
1708 <indexterm><primary>tunefs</primary></indexterm>
1710 <para>The &man.tunefs.8; program can be used to fine-tune a
1711 file system. This program has many different options, but for
1712 now we are only concerned with toggling Soft Updates on and
1713 off, which is done by:</para>
1715 <screen>&prompt.root; <userinput>tunefs -n enable /filesystem</userinput>
1716 &prompt.root; <userinput>tunefs -n disable /filesystem</userinput></screen>
1718 <para>A filesystem cannot be modified with &man.tunefs.8; while
1719 it is mounted. A good time to enable Soft Updates is before any
1720 partitions have been mounted, in single-user mode.</para>
1722 <note><para>It is possible to enable Soft Updates
1723 at filesystem creation time, through use of the <literal>-U</literal>
1724 option to &man.newfs.8;.</para></note>
1726 <para>Soft Updates drastically improves meta-data performance, mainly
1727 file creation and deletion, through the use of a memory cache. We
1728 recommend to use Soft Updates on all of your file systems. There
1729 are two downsides to Soft Updates that you should be aware of: First,
1730 Soft Updates guarantees filesystem consistency in the case of a crash
1731 but could very easily be several seconds (even a minute!) behind
1732 updating the physical disk. If your system crashes you may lose more
1733 work than otherwise. Secondly, Soft Updates delays the freeing of
1734 filesystem blocks. If you have a filesystem (such as the root
1735 filesystem) which is almost full, performing a major update, such as
1736 <command>make installworld</command>, can cause the filesystem to run
1737 out of space and the update to fail.</para>
1740 <title>More Details about Soft Updates</title>
1743 <primary>Soft Updates</primary>
1744 <secondary>details</secondary>
1747 <para>There are two traditional approaches to writing a file
1748 systems meta-data back to disk. (Meta-data updates are
1749 updates to non-content data like inodes or
1750 directories.)</para>
1752 <para>Historically, the default behavior was to write out
1753 meta-data updates synchronously. If a directory had been
1754 changed, the system waited until the change was actually
1755 written to disk. The file data buffers (file contents) were
1756 passed through the buffer cache and backed up
1757 to disk later on asynchronously. The advantage of this
1758 implementation is that it operates safely. If there is
1759 a failure during an update, the meta-data are always in a
1760 consistent state. A file is either created completely
1761 or not at all. If the data blocks of a file did not find
1762 their way out of the buffer cache onto the disk by the time
1763 of the crash, &man.fsck.8; is able to recognize this and
1764 repair the filesystem by setting the file length to
1765 0. Additionally, the implementation is clear and simple.
1766 The disadvantage is that meta-data changes are slow. An
1767 <command>rm -r</command>, for instance, touches all the files
1768 in a directory sequentially, but each directory
1769 change (deletion of a file) will be written synchronously
1770 to the disk. This includes updates to the directory itself,
1771 to the inode table, and possibly to indirect blocks
1772 allocated by the file. Similar considerations apply for
1773 unrolling large hierarchies (<command>tar -x</command>).</para>
1775 <para>The second case is asynchronous meta-data updates. This
1776 is the default for Linux/ext2fs and
1777 <command>mount -o async</command> for *BSD ufs. All
1778 meta-data updates are simply being passed through the buffer
1779 cache too, that is, they will be intermixed with the updates
1780 of the file content data. The advantage of this
1781 implementation is there is no need to wait until each
1782 meta-data update has been written to disk, so all operations
1783 which cause huge amounts of meta-data updates work much
1784 faster than in the synchronous case. Also, the
1785 implementation is still clear and simple, so there is a low
1786 risk for bugs creeping into the code. The disadvantage is
1787 that there is no guarantee at all for a consistent state of
1788 the filesystem. If there is a failure during an operation
1789 that updated large amounts of meta-data (like a power
1790 failure, or someone pressing the reset button),
1792 will be left in an unpredictable state. There is no opportunity
1793 to examine the state of the filesystem when the system
1794 comes up again; the data blocks of a file could already have
1795 been written to the disk while the updates of the inode
1796 table or the associated directory were not. It is actually
1797 impossible to implement a <command>fsck</command> which is
1798 able to clean up the resulting chaos (because the necessary
1799 information is not available on the disk). If the
1800 filesystem has been damaged beyond repair, the only choice
1801 is to use &man.newfs.8; on it and restore it from backup.
1804 <para>The usual solution for this problem was to implement
1805 <emphasis>dirty region logging</emphasis>, which is also
1806 referred to as <emphasis>journaling</emphasis>, although that
1807 term is not used consistently and is occasionally applied
1808 to other forms of transaction logging as well. Meta-data
1809 updates are still written synchronously, but only into a
1810 small region of the disk. Later on they will be moved
1811 to their proper location. Because the logging
1812 area is a small, contiguous region on the disk, there
1813 are no long distances for the disk heads to move, even
1814 during heavy operations, so these operations are quicker
1815 than synchronous updates.
1816 Additionally the complexity of the implementation is fairly
1817 limited, so the risk of bugs being present is low. A disadvantage
1818 is that all meta-data are written twice (once into the
1819 logging region and once to the proper location) so for
1820 normal work, a performance <quote>pessimization</quote>
1821 might result. On the other hand, in case of a crash, all
1822 pending meta-data operations can be quickly either rolled-back
1823 or completed from the logging area after the system comes
1824 up again, resulting in a fast filesystem startup.</para>
1826 <para>Kirk McKusick, the developer of Berkeley FFS,
1827 solved this problem with Soft Updates: all pending
1828 meta-data updates are kept in memory and written out to disk
1829 in a sorted sequence (<quote>ordered meta-data
1830 updates</quote>). This has the effect that, in case of
1831 heavy meta-data operations, later updates to an item
1832 <quote>catch</quote> the earlier ones if the earlier ones are still in
1833 memory and have not already been written to disk. So all
1834 operations on, say, a directory are generally performed in
1835 memory before the update is written to disk (the data
1836 blocks are sorted according to their position so
1837 that they will not be on the disk ahead of their meta-data).
1838 If the system crashes, this causes an implicit <quote>log
1839 rewind</quote>: all operations which did not find their way
1840 to the disk appear as if they had never happened. A
1841 consistent filesystem state is maintained that appears to
1842 be the one of 30 to 60 seconds earlier. The
1843 algorithm used guarantees that all resources in use
1844 are marked as such in their appropriate bitmaps: blocks and inodes.
1845 After a crash, the only resource allocation error
1846 that occurs is that resources are
1847 marked as <quote>used</quote> which are actually <quote>free</quote>.
1848 &man.fsck.8; recognizes this situation,
1849 and frees the resources that are no longer used. It is safe to
1850 ignore the dirty state of the filesystem after a crash by
1851 forcibly mounting it with <command>mount -f</command>. In
1852 order to free resources that may be unused, &man.fsck.8;
1853 needs to be run at a later time.</para>
1855 <para>The advantage is that meta-data operations are nearly as
1856 fast as asynchronous updates (i.e. faster than with
1857 <emphasis>logging</emphasis>, which has to write the
1858 meta-data twice). The disadvantages are the complexity of
1859 the code (implying a higher risk for bugs in an area that
1860 is highly sensitive regarding loss of user data), and a
1861 higher memory consumption. Additionally there are some
1862 idiosyncrasies one has to get used to.
1863 After a crash, the state of the filesystem appears to be
1864 somewhat <quote>older</quote>. In situations where
1865 the standard synchronous approach would have caused some
1866 zero-length files to remain after the
1867 <command>fsck</command>, these files do not exist at all
1868 with a Soft Updates filesystem because neither the meta-data
1869 nor the file contents have ever been written to disk.
1870 Disk space is not released until the updates have been
1871 written to disk, which may take place some time after
1872 running <command>rm</command>. This may cause problems
1873 when installing large amounts of data on a filesystem
1874 that does not have enough free space to hold all the files
1880 <sect1 id="configtuning-kernel-limits">
1881 <title>Tuning Kernel Limits</title>
1884 <primary>tuning</primary>
1885 <secondary>kernel limits</secondary>
1888 <sect2 id="file-process-limits">
1889 <title>File/Process Limits</title>
1891 <sect3 id="kern-maxfiles">
1892 <title><varname>kern.maxfiles</varname></title>
1895 <primary><varname>kern.maxfiles</varname></primary>
1898 <para><varname>kern.maxfiles</varname> can be raised or
1899 lowered based upon your system requirements. This variable
1900 indicates the maximum number of file descriptors on your
1901 system. When the file descriptor table is full,
1902 <errorname>file: table is full</errorname> will show up repeatedly
1903 in the system message buffer, which can be viewed with the
1904 <command>dmesg</command> command.</para>
1906 <para>Each open file, socket, or fifo uses one file
1907 descriptor. A large-scale production server may easily
1908 require many thousands of file descriptors, depending on the
1909 kind and number of services running concurrently.</para>
1911 <para><varname>kern.maxfile</varname>'s default value is
1912 dictated by the <option>MAXUSERS</option> option in your
1913 kernel configuration file. <varname>kern.maxfiles</varname> grows
1914 proportionally to the value of <option>MAXUSERS</option>. When
1915 compiling a custom kernel, it is a good idea to set this kernel
1916 configuration option according to the uses of your system. From
1917 this number, the kernel is given most of its pre-defined limits.
1918 Even though a production machine may not actually have 256 users
1919 connected at once, the resources needed may be similar to a
1920 high-scale web server.</para>
1922 <note><para>Setting <option>MAXUSERS</option> to
1923 <literal>0</literal> in your kernel configuration file will choose
1924 a reasonable default value based on the amount of RAM present in
1925 your system. It is set to 0 in the default GENERIC kernel.</para></note>
1930 <title><varname>kern.ipc.somaxconn</varname></title>
1933 <primary><varname>kern.ipc.somaxconn</varname></primary>
1936 <para>The <varname>kern.ipc.somaxconn</varname> sysctl variable
1937 limits the size of the listen queue for accepting new TCP
1938 connections. The default value of <literal>128</literal> is
1939 typically too low for robust handling of new connections in a
1940 heavily loaded web server environment. For such environments, it
1941 is recommended to increase this value to <literal>1024</literal> or
1942 higher. The service daemon may itself limit the listen queue size
1943 (e.g. &man.sendmail.8;, or <application>Apache</application>) but
1944 will often have a directive in its configuration file to adjust
1945 the queue size. Large listen queues also do a better job of
1946 avoiding Denial of Service (<abbrev>DoS</abbrev>) attacks.</para>
1951 <title>Network Limits</title>
1953 <para>The <literal>NMBCLUSTERS</literal> kernel configuration
1954 option dictates the amount of network Mbufs available to the
1955 system. A heavily-trafficked server with a low number of Mbufs
1956 will hinder &os;'s ability. Each cluster represents
1957 approximately 2 K of memory, so a value of 1024 represents 2
1958 megabytes of kernel memory reserved for network buffers. A
1959 simple calculation can be done to figure out how many are
1960 needed. If you have a web server which maxes out at 1000
1961 simultaneous connections, and each connection eats a 16 K receive
1962 and 16 K send buffer, you need approximately 32 MB worth of
1963 network buffers to cover the web server. A good rule of thumb is
1964 to multiply by 2, so 2x32 MB / 2 KB =
1965 64 MB / 2 kB = 32768. We recommend
1966 values between 4096 and 32768 for machines with greater amounts
1967 of memory. Under no circumstances should you specify an
1968 arbitrarily high value for this parameter as it could lead to a
1969 boot time crash. The <option>-m</option> option to
1970 &man.netstat.1; may be used to observe network cluster
1971 use. <varname>kern.ipc.nmbclusters</varname> loader tunable should
1972 be used to tune this at boot time.</para>
1974 <para>For busy servers that make extensive use of the
1975 &man.sendfile.2; system call, it may be necessary to increase
1976 the number of &man.sendfile.2; buffers via the
1977 <literal>NSFBUFS</literal> kernel configuration option or by
1978 setting its value in <filename>/boot/loader.conf</filename>
1979 (see &man.loader.8; for details). A common indicator that
1980 this parameter needs to be adjusted is when processes are seen
1981 in the <literal>sfbufa</literal> state. The sysctl
1982 variable <varname>kern.ipc.nsfbufs</varname> is a read-only
1983 glimpse at the kernel configured variable. This parameter
1984 nominally scales with <varname>kern.maxusers</varname>,
1985 however it may be necessary to tune accordingly.</para>
1988 <para>Even though a socket has been marked as non-blocking,
1989 calling &man.sendfile.2; on the non-blocking socket may
1990 result in the &man.sendfile.2; call blocking until enough
1991 <literal>struct sf_buf</literal>'s are made
1996 <title><varname>net.inet.ip.portrange.*</varname></title>
1999 <primary>net.inet.ip.portrange.*</primary>
2002 <para>The <varname>net.inet.ip.portrange.*</varname> sysctl
2003 variables control the port number ranges automatically bound to TCP
2004 and UDP sockets. There are three ranges: a low range, a default
2005 range, and a high range. Most network programs use the default
2006 range which is controlled by the
2007 <varname>net.inet.ip.portrange.first</varname> and
2008 <varname>net.inet.ip.portrange.last</varname>, which default to
2009 1024 and 5000, respectively. Bound port ranges are used for
2010 outgoing connections, and it is possible to run the system out of
2011 ports under certain circumstances. This most commonly occurs
2012 when you are running a heavily loaded web proxy. The port range
2013 is not an issue when running servers which handle mainly incoming
2014 connections, such as a normal web server, or has a limited number
2015 of outgoing connections, such as a mail relay. For situations
2016 where you may run yourself out of ports, it is recommended to
2017 increase <varname>net.inet.ip.portrange.last</varname> modestly.
2018 A value of <literal>10000</literal>, <literal>20000</literal> or
2019 <literal>30000</literal> may be reasonable. You should also
2020 consider firewall effects when changing the port range. Some
2021 firewalls may block large ranges of ports (usually low-numbered
2022 ports) and expect systems to use higher ranges of ports for
2023 outgoing connections — for this reason it is recommended that
2024 <varname>net.inet.ip.portrange.first</varname> be lowered.</para>
2028 <title>TCP Bandwidth Delay Product</title>
2031 <primary>TCP Bandwidth Delay Product Limiting</primary>
2032 <secondary><varname>net.inet.tcp.inflight_enable</varname></secondary>
2035 <para>The TCP Bandwidth Delay Product Limiting is similar to
2036 TCP/Vegas in NetBSD.
2038 <indexterm><primary>&netbsd;</primary></indexterm>
2041 enabled by setting <varname>net.inet.tcp.inflight_enable</varname>
2042 sysctl variable to <literal>1</literal>. The system will attempt
2043 to calculate the bandwidth delay product for each connection and
2044 limit the amount of data queued to the network to just the amount
2045 required to maintain optimum throughput.</para>
2047 <para>This feature is useful if you are serving data over modems,
2048 Gigabit Ethernet, or even high speed WAN links (or any other link
2049 with a high bandwidth delay product), especially if you are also
2050 using window scaling or have configured a large send window. If
2051 you enable this option, you should also be sure to set
2052 <varname>net.inet.tcp.inflight_debug</varname> to
2053 <literal>0</literal> (disable debugging), and for production use
2054 setting <varname>net.inet.tcp.inflight_min</varname> to at least
2055 <literal>6144</literal> may be beneficial. However, note that
2056 setting high minimums may effectively disable bandwidth limiting
2057 depending on the link. The limiting feature reduces the amount of
2058 data built up in intermediate route and switch packet queues as
2059 well as reduces the amount of data built up in the local host's
2060 interface queue. With fewer packets queued up, interactive
2061 connections, especially over slow modems, will also be able to
2062 operate with lower <emphasis>Round Trip Times</emphasis>. However,
2063 note that this feature only effects data transmission (uploading
2064 / server side). It has no effect on data reception (downloading).
2067 <para>Adjusting <varname>net.inet.tcp.inflight_stab</varname> is
2068 <emphasis>not</emphasis> recommended. This parameter defaults to
2069 20, representing 2 maximal packets added to the bandwidth delay
2070 product window calculation. The additional window is required to
2071 stabilize the algorithm and improve responsiveness to changing
2072 conditions, but it can also result in higher ping times over slow
2073 links (though still much lower than you would get without the
2074 inflight algorithm). In such cases, you may wish to try reducing
2075 this parameter to 15, 10, or 5; and may also have to reduce
2076 <varname>net.inet.tcp.inflight_min</varname> (for example, to
2077 3500) to get the desired effect. Reducing these parameters
2078 should be done as a last resort only.</para>
2083 <sect1 id="adding-swap-space">
2084 <title>Adding Swap Space</title>
2086 <para>No matter how well you plan, sometimes a system does not run
2087 as you expect. If you find you need more swap space, it is
2088 simple enough to add. You have three ways to increase swap
2089 space: adding a new hard drive, enabling swap over NFS, and
2090 creating a swap file on an existing partition.</para>
2092 <sect2 id="new-drive-swap">
2093 <title>Swap on a New Hard Drive</title>
2095 <para>The best way to add swap, of course, is to use this as an
2096 excuse to add another hard drive. You can always use another
2097 hard drive, after all. If you can do this, go reread the
2098 discussion about swap space in <xref linkend="configtuning-initial">
2099 for some suggestions on how to best arrange your swap.</para>
2102 <sect2 id="nfs-swap">
2103 <title>Swapping over NFS</title>
2105 <para>Swapping over NFS is only recommended if you do not have a
2106 local hard disk to swap to. Even though &os; has an excellent
2107 NFS implementation, NFS swapping will be limited
2108 by the available network bandwidth and puts an additional
2109 burden on the NFS server.</para>
2112 <sect2 id="create-swapfile">
2113 <title>Swapfiles</title>
2115 <para>You can create a file of a specified size to use as a swap
2116 file. In our example here we will use a 64MB file called
2117 <filename>/usr/swap0</filename>. You can use any name you
2118 want, of course.</para>
2121 <title>Creating a Swapfile</title>
2125 <para>Be certain that your kernel configuration includes
2126 the vnode driver. It is <emphasis>not</emphasis> in recent versions of
2127 <filename>GENERIC</filename>.</para>
2129 <programlisting>pseudo-device vn 1 #Vnode driver (turns a file into a device)</programlisting>
2133 <para>Create a vn-device:</para>
2134 <screen>&prompt.root; <userinput>cd /dev</userinput>
2135 &prompt.root; <userinput>sh MAKEDEV vn0</userinput></screen>
2139 <para>Create a swapfile (<filename>/usr/swap0</filename>):</para>
2141 <screen>&prompt.root; <userinput>dd if=/dev/zero of=/usr/swap0 bs=1024k count=64</userinput></screen>
2145 <para>Set proper permissions on (<filename>/usr/swap0</filename>):</para>
2147 <screen>&prompt.root; <userinput>chmod 0600 /usr/swap0</userinput></screen>
2151 <para>Enable the swap file in <filename>/etc/rc.conf</filename>:</para>
2153 <programlisting>swapfile="/usr/swap0" # Set to name of swapfile if aux swapfile desired.</programlisting>
2158 <para>Reboot the machine or to enable the swap file immediately,
2161 <screen>&prompt.root; <userinput>vnconfig -e /dev/vn0b /usr/swap0 swap</userinput></screen>
2169 <sect1 id="acpi-overview">
2173 <firstname>Hiten</firstname>
2174 <surname>Pandya</surname>
2175 <contrib>Written by </contrib>
2178 <firstname>Tom</firstname>
2179 <surname>Rhodes</surname>
2184 <title>Power and Resource Management</title>
2186 <para>It is very important to utilize hardware resources in an
2187 efficient manner. Before <acronym>ACPI</acronym> was introduced,
2188 it was very difficult and inflexible for operating systems to manage
2189 the power usage and thermal properties of a system. The hardware was
2190 controlled by some sort of <acronym>BIOS</acronym> embedded
2191 interface, such as <emphasis>Plug and Play BIOS (PNPBIOS)</emphasis>, or
2192 <emphasis>Advanced Power Management (APM)</emphasis> and so on.
2193 Power and Resource Management is one of the key components of a modern
2194 operating system. For example, you may want an operating system to
2195 monitor system limits (and possibly alert you) in case your system
2196 temperature increased unexpectedly.</para>
2198 <para>In this section, we will provide
2199 comprehensive information about <acronym>ACPI</acronym>. References
2200 will be provided for further reading at the end. Please be aware
2201 that <acronym>ACPI</acronym> is available on &os; systems as a
2202 default kernel module. </para>
2204 <sect2 id="acpi-intro">
2205 <title>What Is ACPI?</title>
2207 <para>Advanced Configuration and Power Interface
2208 (<acronym>ACPI</acronym>) is a standard written by
2209 an alliance of vendors to provide a standard interface for
2210 hardware resources and power management (hence the name).
2211 It is a key element in <emphasis>Operating System-directed
2212 configuration and Power Management</emphasis>, i.e.: it provides
2213 more control and flexibility to the operating system
2214 (<acronym>OS</acronym>).
2215 Modern systems <quote>stretched</quote> the limits of the
2216 current Plug and Play interfaces (such as APM), prior to the introduction of
2217 <acronym>ACPI</acronym>. <acronym>ACPI</acronym> is the direct
2218 successor to <acronym>APM</acronym>
2219 (Advanced Power Management).</para>
2222 <sect2 id="acpi-old-spec">
2223 <title>Shortcomings of Advanced Power Management (APM)</title>
2225 <para>The <emphasis>Advanced Power Management (APM)</emphasis>
2226 facility control's the power usage of a system based on its
2227 activity. The APM BIOS is supplied by the (system) vendor and
2228 it is specific to the hardware platform. An APM driver in the
2229 OS mediates access to the <emphasis>APM Software Interface</emphasis>,
2230 which allows management of power levels.</para>
2232 <para>There are four major problems in APM. Firstly, power
2233 management is done by the (vendor-specific) BIOS, and the OS
2234 does not have any knowledge of it. One example of this, is when
2235 the user sets idle-time values for a hard drive in the APM BIOS,
2236 that when exceeded, it (BIOS) would spin down the hard drive,
2237 without the consent of the OS. Secondly, the APM logic is
2238 embedded in the BIOS, and it operates outside the scope of the
2239 OS. This means users can only fix problems in their APM BIOS by
2240 flashing a new one into the ROM; which, is a very dangerous
2241 procedure, and if it fails, it could leave the system in an
2242 unrecoverable state. Thirdly, APM is a vendor-specific
2243 technology, which, means that there is a lot or parity
2244 (duplication of efforts) and bugs found in one vendor's BIOS,
2245 may not be solved in others. Last but not the least, the APM
2246 BIOS did not have enough room to implement a sophisticated power
2247 policy, or one that can adapt very well to the purpose of the
2250 <para><emphasis>Plug and Play BIOS (PNPBIOS)</emphasis> was
2251 unreliable in many situations. PNPBIOS is 16-bit technology,
2252 so the OS has to use 16-bit emulation in order to
2253 <quote>interface</quote> with PNPBIOS methods.</para>
2255 <para>The &os; <acronym>APM</acronym> driver is documented in
2256 the &man.apm.4; manual page.</para>
2259 <sect2 id="acpi-config">
2260 <title>Configuring <acronym>ACPI</acronym></title>
2262 <para>The <filename>acpi.ko</filename> driver is loaded by default
2263 at start up by the &man.loader.8; and should <emphasis>not</emphasis>
2264 be compiled into the kernel. The reasoning behind this is that modules
2265 are easier to work with, say if switching to another <filename>acpi.ko</filename>
2266 without doing a kernel rebuild. This has the advantage of making testing easier.
2267 Another reason is that starting <acronym>ACPI</acronym> after a system has been
2268 brought up is not too useful, and in some cases can be fatal. In doubt, just
2269 disable <acronym>ACPI</acronym> all together. This driver should not and can not
2270 be unloaded because the system bus uses it for various hardware interactions.
2271 <acronym>ACPI</acronym> can be disabled with the &man.acpiconf.8; utility.
2272 In fact most of the interaction with <acronym>ACPI</acronym> can be done via
2273 &man.acpiconf.8;. Basically this means, if anything about <acronym>ACPI</acronym>
2274 is in the &man.dmesg.8; output, then most likely it is already running.</para>
2276 <note><para><acronym>ACPI</acronym> and <acronym>APM</acronym> cannot coexist and
2277 should be used separately. The last one to load will terminate if the driver
2278 notices the other running.</para></note>
2280 <para>In the simplest form, <acronym>ACPI</acronym> can be used to put the
2281 system into a sleep mode with &man.acpiconf.8;, the <option>-s</option>
2282 flag, and a <literal>1-5</literal> option. Most users will only need
2283 <literal>1</literal>. Option <literal>5</literal> will do a soft-off
2284 which is the same action as:</para>
2286 <screen>&prompt.root; <userinput>halt -p</userinput></screen>
2288 <para>The other options are available. Check out the &man.acpiconf.8;
2289 manual page for more information.</para>
2293 <sect1 id="ACPI-debug">
2297 <firstname>Nate</firstname>
2298 <surname>Lawson</surname>
2299 <contrib>Written by </contrib>
2304 <firstname>Peter</firstname>
2305 <surname>Schultz</surname>
2306 <contrib>With contributions from </contrib>
2309 <firstname>Tom</firstname>
2310 <surname>Rhodes</surname>
2315 <title>Using and Debugging &os; <acronym>ACPI</acronym></title>
2317 <para><acronym>ACPI</acronym> is a fundamentally new way of
2318 discovering devices, managing power usage, and providing
2319 standardized access to various hardware previously managed
2320 by the <acronym>BIOS</acronym>. Progress is being made toward
2321 <acronym>ACPI</acronym> working on all systems, but bugs in some
2322 motherboards' <firstterm><acronym>ACPI</acronym> Machine
2323 Language</firstterm> (<acronym>AML</acronym>) bytecode,
2324 incompleteness in &os;'s kernel subsystems, and bugs in the Intel
2325 <acronym>ACPI-CA</acronym> interpreter continue to appear.</para>
2327 <para>This document is intended to help you assist the &os;
2328 <acronym>ACPI</acronym> maintainers in identifying the root cause
2329 of problems you observe and debugging and developing a solution.
2330 Thanks for reading this and we hope we can solve your system's
2333 <sect2 id="ACPI-submitdebug">
2334 <title>Submitting Debugging Information</title>
2337 <para>Before submitting a problem, be sure you are running the latest
2338 <acronym>BIOS</acronym> version and, if available, embedded
2339 controller firmware version.</para>
2342 <para>For those of you that want to submit a problem right away,
2343 please send the following information to
2344 &a.bugs.name;</para>
2348 <para>Description of the buggy behavior, including system type
2349 and model and anything that causes the bug to appear. Also,
2350 please note as accurately as possible when the bug began
2351 occurring if it is new for you.</para>
2355 <para>The dmesg output after <quote>boot
2356 <option>-v</option></quote>, including any error messages
2357 generated by you exercising the bug.</para>
2361 <para>dmesg output from <quote>boot
2362 <option>-v</option></quote> with <acronym>ACPI</acronym>
2363 disabled, if disabling it helps fix the problem.</para>
2367 <para>Output from <quote>sysctl hw.acpi</quote>. This is also
2368 a good way of figuring out what features your system
2373 <para><acronym>URL</acronym> where your
2374 <firstterm><acronym>ACPI</acronym> Source Language</firstterm>
2375 (<acronym>ASL</acronym>)
2376 can be found. Do <emphasis>not</emphasis> send the
2377 <acronym>ASL</acronym> directly to the list as it can be
2378 very large. Generate a copy of your <acronym>ASL</acronym>
2379 by running this command:</para>
2381 <screen>&prompt.root; <userinput>acpidump -t -d > <replaceable>name</replaceable>-<replaceable>system</replaceable>.asl</userinput></screen>
2383 <para>(Substitute your login name for
2384 <replaceable>name</replaceable> and manufacturer/model for
2385 <replaceable>system</replaceable>. Example:
2386 <filename>njl-FooCo6000.asl</filename>)</para>
2392 <sect2 id="ACPI-background">
2393 <title>Background</title>
2395 <para><acronym>ACPI</acronym> is present in all modern computers
2396 that conform to the ia32 (x86), ia64 (Itanium), and amd64 (AMD)
2397 architectures. The full standard has many features including
2398 <acronym>CPU</acronym> performance management, power planes
2399 control, thermal zones, various battery systems, embedded
2400 controllers, and bus enumeration. Most systems implement less
2401 than the full standard. For instance, a desktop system usually
2402 only implements the bus enumeration parts while a laptop might
2403 have cooling and battery management support as well. Laptops
2404 also have suspend and resume, with their own associated
2407 <para>An <acronym>ACPI</acronym>-compliant system has various
2408 components. The <acronym>BIOS</acronym> and chipset vendors
2409 provide various fixed tables (e.g., <acronym>FADT</acronym>)
2410 in memory that specify things like the <acronym>APIC</acronym>
2411 map (used for <acronym>SMP</acronym>), config registers, and
2412 simple configuration values. Additionally, a table of bytecode
2413 (the <firstterm>Differentiated System Description Table</firstterm>
2414 <acronym>DSDT</acronym>) is provided that specifies a
2415 tree-like name space of devices and methods.</para>
2417 <para>The <acronym>ACPI</acronym> driver must parse the fixed
2418 tables, implement an interpreter for the bytecode, and modify
2419 device drivers and the kernel to accept information from the
2420 <acronym>ACPI</acronym> subsystem. For &os;, Intel has
2421 provided an interpreter (<acronym>ACPI-CA</acronym>) that is
2422 shared with Linux and &netbsd;.
2424 <indexterm><primary>&netbsd;</primary></indexterm>
2427 <acronym>ACPI-CA</acronym> source code is
2428 <filename role="directory">src/sys/contrib/dev/acpica-unix-YYYYMMDD</filename>,
2429 where YYYYMMDD is the release date of the ACPI-CA source code. The
2430 glue code that allows <acronym>ACPI-CA</acronym> to work on
2431 &os; is in <filename>src/sys/dev/acpica5/Osd</filename>. Finally,
2432 drivers that implement various <acronym>ACPI</acronym> devices
2433 are found in <filename role="directory">src/sys/dev/acpica5</filename>,
2434 and architecture-dependent code resides in
2435 <filename role="directory">/sys/<replaceable>arch</replaceable>/acpica5</filename>.
2439 <sect2 id="ACPI-comprob">
2440 <title>Common Problems</title>
2442 <para>For <acronym>ACPI</acronym> to work correctly, all the parts
2443 have to work correctly. Here are some common problems, in order
2444 of frequency of appearance, and some possible workarounds or
2448 <title>Suspend/Resume</title>
2450 <para><acronym>ACPI</acronym> has three suspend to
2451 <acronym>RAM</acronym> (<acronym>STR</acronym>) states,
2452 <literal>S1</literal>-<literal>S3</literal>, and one suspend
2453 to disk state (<literal>STD</literal>), called
2454 <literal>S4</literal>. <literal>S5</literal> is
2455 <quote>soft off</quote> and is the normal state your system
2456 is in when plugged in but not powered up.
2457 <literal>S4</literal> can actually be implemented two separate
2458 ways. <literal>S4</literal><acronym>BIOS</acronym> is a
2459 <acronym>BIOS</acronym>-assisted suspend to disk.
2460 <literal>S4</literal><acronym>OS</acronym> is implemented
2461 entirely by the operating system.</para>
2463 <para>Start by checking <command>sysctl</command>
2464 <option>hw.acpi</option> for the suspend-related items. Here
2465 are the results for my Thinkpad:</para>
2467 <screen>hw.acpi.supported_sleep_state: S3 S4 S5</screen>
2468 <screen>hw.acpi.s4bios: 0</screen>
2470 <para>This means that I can use <command>acpiconf -s</command>
2471 to test <literal>S3</literal>,
2472 <literal>S4</literal><acronym>OS</acronym>, and
2473 <literal>S5</literal>. If <option>s4bios</option> was one
2474 (<literal>1</literal>), I would have
2475 <literal>S4</literal><acronym>BIOS</acronym>
2476 support instead of <literal>S4</literal>
2477 <acronym>OS</acronym>.</para>
2479 <para>When testing suspend/resume, start with
2480 <literal>S1</literal>, if supported. This state is most
2481 likely to work since it doesn't require much driver support.
2482 No one has implemented <literal>S2</literal> but if you have
2483 it, it's similar to <literal>S1</literal>. The next thing
2484 to try is <literal>S3</literal>. This is the deepest
2485 <acronym>STR</acronym> state and requires a lot of driver
2486 support to properly reinitialize your hardware. If you have
2487 problems resuming, feel free to email the &a.bugs.name; list but
2488 do not expect the problem to be resolved since there are a lot
2489 of drivers/hardware that need more testing and work.</para>
2491 <para>To help isolate the problem, remove as many drivers from
2492 your kernel as possible. If it works, you can narrow down
2493 which driver is the problem by loading drivers until it fails
2494 again. Typically binary drivers like
2495 <filename>nvidia.ko</filename>, <application>X11</application>
2496 display drivers, and <acronym>USB</acronym> will have the most
2497 problems while Ethernet interfaces usually work fine. If you
2498 can load/unload the drivers ok, you can automate this by
2499 putting the appropriate commands in
2500 <filename>/etc/rc.suspend</filename> and
2501 <filename>/etc/rc.resume</filename>. There is a
2502 commented-out example for unloading and loading a driver. Try
2503 setting <option>hw.acpi.reset_video</option> to zero (0) if
2504 your display is messed up after resume. Try setting longer or
2505 shorter values for <option>hw.acpi.sleep_delay</option> to see
2506 if that helps.</para>
2508 <para>Another thing to try is load a recent Linux distribution
2509 with <acronym>ACPI</acronym> support and test their
2510 suspend/resume support on the same hardware. If it works
2511 on Linux, it's likely a &os; driver problem and narrowing down
2512 which driver causes the problems will help us fix the problem.
2513 Note that the <acronym>ACPI</acronym> maintainers do not
2514 usually maintain other drivers (e.g sound,
2515 <acronym>ATA</acronym>, etc.) so any work done on tracking
2516 down a driver problem should probably eventually be posted
2517 to the &a.bugs.name; list and mailed to the driver
2518 maintainer. If you are feeling adventurous, go ahead and
2519 start putting some debugging &man.printf.3;s in a problematic
2520 driver to track down where in its resume function it
2523 <para>Finally, try disabling <acronym>ACPI</acronym> and
2524 enabling <acronym>APM</acronym> instead. If suspend/resume
2525 works with <acronym>APM</acronym>, you may be better off
2526 sticking with <acronym>APM</acronym>, especially on older
2527 hardware (pre-2000). It took vendors a while to get
2528 <acronym>ACPI</acronym> support correct and older hardware is
2529 more likely to have <acronym>BIOS</acronym> problems with
2530 <acronym>ACPI</acronym>.</para>
2534 <title>System Hangs (temporary or permanent)</title>
2536 <para>Most system hangs are a result of lost interrupts or an
2537 interrupt storm. Chipsets have a lot of problems based on how
2538 the <acronym>BIOS</acronym> configures interrupts before boot,
2539 correctness of the <acronym>APIC</acronym>
2540 (<acronym>MADT</acronym>) table, and routing of the
2541 <firstterm>System Control Interrupt</firstterm>
2542 (<acronym>SCI</acronym>).</para>
2544 <para>Interrupt storms can be distinguished from lost interrupts
2545 by checking the output of <command>vmstat -i</command>
2546 and looking at the line that has
2547 <literal>acpi0</literal>. If the counter is increasing at more
2548 than a couple per second, you have an interrupt storm. If the
2549 system appears hung, try breaking to <acronym>DDB</acronym>
2550 (<keycombo action="simul"><keycap>CTRL</keycap>
2551 <keycap>ALT</keycap><keycap>ESC</keycap></keycombo> on
2552 console) and type <option>show interrupts</option>.</para>
2554 <para>Your best hope when dealing with interrupt problems is to
2555 try disabling <acronym>APIC</acronym> support with
2556 <literal>hint.apic.0.disabled="1"</literal> in
2557 <filename>loader.conf</filename>.</para>
2561 <title>Panics</title>
2563 <para>Panics are relatively rare for <acronym>ACPI</acronym> and
2564 are the top priority to be fixed. The first step is to
2565 isolate the steps to reproduce the panic (if possible)
2566 and get a backtrace. Follow the advice for enabling
2567 <option>options DDB</option> and setting up a serial console
2568 (see <xref linkend="serialconsole-ddb">)
2569 or setting up a &man.dump.8; partition. You can get a
2570 backtrace in <acronym>DDB</acronym> with
2571 <option>tr</option>. If you have to handwrite the
2572 backtrace, be sure to at least get the lowest five (5) and top
2573 five (5) lines in the trace.</para>
2575 <para>Then, try to isolate the problem by booting with
2576 <acronym>ACPI</acronym> disabled. If that works, you can
2577 isolate the <acronym>ACPI</acronym> subsystem by using various
2578 values of <option>debug.acpi.disable</option>. See the
2579 &man.acpi.4; manual page for some examples.</para>
2583 <title>System Powers Up After Suspend or Shutdown</title>
2584 <para>First, try setting
2585 <option>hw.acpi.disable_on_poweroff=</option><quote>0</quote>
2586 in &man.loader.conf.5;. This keeps <acronym>ACPI</acronym>
2587 from disabling various events during the shutdown process.
2588 Some systems need this value set to <quote>1</quote> (the
2589 default) for the same reason. This usually fixes
2590 the problem of a system powering up spontaneously after a
2591 suspend or poweroff.</para>
2595 <title>Other Problems</title>
2597 <para>If you have other problems with <acronym>ACPI</acronym>
2598 (working with a docking station, devices not detected, etc.),
2599 please email a description to the mailing list as well;
2600 however, some of these issues may be related to unfinished
2601 parts of the <acronym>ACPI</acronym> subsystem so they might
2602 take a while to be implemented. Please be patient and
2603 prepared to test patches we may send you.</para>
2607 <sect2 id="ACPI-aslanddump">
2608 <title><acronym>ASL</acronym>, <command>acpidump</command>, and
2609 <acronym>IASL</acronym></title>
2611 <para>The most common problem is the <acronym>BIOS</acronym>
2612 vendors providing incorrect (or outright buggy!) bytecode. This
2613 is usually manifested by kernel console messages like
2616 <screen>ACPI-1287: *** Error: Method execution failed [\\_SB_.PCI0.LPC0.FIGD._STA] \\
2617 (Node 0xc3f6d160), AE_NOT_FOUND</screen>
2619 <para>Often, you can resolve these problems by updating your
2620 <acronym>BIOS</acronym> to the latest revision. Most console
2621 messages are harmless but if you have other problems like
2622 battery status not working, they're a good place to start
2623 looking for problems in the <acronym>AML</acronym>. The
2624 bytecode, known as <acronym>AML</acronym>, is compiled from a
2625 source language called <acronym>ASL</acronym>. The
2626 <acronym>AML</acronym> is found in the table known as the
2627 <acronym>DSDT</acronym>. To get a copy of your
2628 <acronym>ASL</acronym>, use &man.acpidump.8;. You should use
2629 both the <option>-t</option> (show contents of the fixed tables)
2630 and <option>-d</option> (disassemble <acronym>AML</acronym> to
2631 <acronym>ASL</acronym>) options. See the
2632 <link linkend="ACPI-submitdebug">Submitting Debugging
2633 Information</link> section for an example syntax.</para>
2635 <para>The simplest first check you can do is to recompile your
2636 <acronym>ASL</acronym> to check for errors. Warnings can
2637 usually be ignored but errors are bugs that will usually prevent
2638 <acronym>ACPI</acronym> from working correctly. To recompile
2639 your <acronym>ASL</acronym>, issue the following command:</para>
2641 <screen>&prompt.root; <userinput>iasl your.asl</userinput></screen>
2644 <sect2 id="ACPI-fixasl">
2645 <title>Fixing Your <acronym>ASL</acronym></title>
2647 <para>In the long run, our goal is for almost everyone to have
2648 <acronym>ACPI</acronym> work without any user intervention. At
2649 this point, however, we are still developing workarounds for
2650 common mistakes made by the <acronym>BIOS</acronym> vendors.
2651 The Microsoft interpreter (<filename>acpi.sys</filename> and
2652 <filename>acpiec.sys</filename>) does not strictly check for
2653 adherence to the standard, and thus many <acronym>BIOS</acronym>
2654 vendors who only test <acronym>ACPI</acronym> under Windows
2655 never fix their <acronym>ASL</acronym>. We hope to continue to
2656 identify and document exactly what non-standard behavior is
2657 allowed by Microsoft's interpreter and replicate it so &os; can
2658 work without forcing users to fix the <acronym>ASL</acronym>.
2659 As a workaround and to help us identify behavior, you can fix
2660 the <acronym>ASL</acronym> manually. If this works for you,
2661 please send a &man.diff.1; of the old and new
2662 <acronym>ASL</acronym> so we can possibly work around the buggy
2663 behavior in <acronym>ACPI-CA</acronym> and thus make your fix
2666 <para>Here is a list of common error messages, their cause, and
2667 how to fix them:</para>
2670 <title>_OS dependencies</title>
2672 <para>Some <acronym>AML</acronym> assumes the world consists of
2673 various Windows versions. You can tell &os; to claim it is
2674 any <acronym>OS</acronym> to see if this fixes problems you
2675 may have. An easy way to override this is to set
2676 <option>hw.acpi.osname</option>=<quote>Windows 2001</quote>
2677 in <filename>/boot/loader.conf</filename> or other similar
2678 strings you find in the <acronym>ASL</acronym>.</para>
2682 <title>Missing Return statements</title>
2684 <para>Some methods do not explicitly return a value as the
2685 standard requires. While <acronym>ACPI-CA</acronym>
2686 does not handle this, &os; has a workaround that allows it to
2687 return the value implicitly. You can also add explicit
2688 Return statements where required if you know what value should
2689 be returned. To force <command>iasl</command> to compile the
2690 <acronym>ASL</acronym>, use the <option>-f</option>
2695 <title>Overriding the Default <acronym>AML</acronym></title>
2697 <para>After you customize <filename>your.asl</filename>, you
2698 will want to compile it, run:</para>
2700 <screen>&prompt.root; <userinput>iasl your.asl</userinput></screen>
2702 <para>You can add the <option>-f</option> flag to force creation
2703 of the <acronym>AML</acronym>, even if there are errors during
2704 compilation. Remember that some errors (e.g., missing Return
2705 statements) are automatically worked around by the
2708 <para><filename>DSDT.aml</filename> is the default output
2709 filename for <command>iasl</command>. You can load this
2710 instead of your <acronym>BIOS</acronym>'s buggy copy (which
2711 is still present in flash memory) by editing
2712 <filename>/boot/loader.conf</filename> as
2715 <programlisting>acpi_dsdt_load="YES"
2716 acpi_dsdt_name="/boot/DSDT.aml"</programlisting>
2718 <para>Be sure to copy your <filename>DSDT.aml</filename> to the
2719 <filename role="directory">/boot</filename> directory.</para>
2723 <sect2 id="ACPI-debugoutput">
2724 <title>Getting Debugging Output From
2725 <acronym>ACPI</acronym></title>
2727 <para>The <acronym>ACPI</acronym> driver has a very flexible
2728 debugging facility. It allows you to specify a set of subsystems
2729 as well as the level of verbosity. The subsystems you wish to
2730 debug are specified as <quote>layers</quote> and are broken down
2731 into <acronym>ACPI-CA</acronym> components (ACPI_ALL_COMPONENTS)
2732 and <acronym>ACPI</acronym> hardware support (ACPI_ALL_DRIVERS).
2733 The verbosity of debugging output is specified as the
2734 <quote>level</quote> and ranges from ACPI_LV_ERROR (just report
2735 errors) to ACPI_LV_VERBOSE (everything). The
2736 <quote>level</quote> is a bitmask so multiple options can be set
2737 at once, separated by spaces. In practice, you will want to use
2738 a serial console to log the output if it is so long
2739 it flushes the console message buffer. </para>
2741 <para>Debugging output is not enabled by default. To enable it,
2742 add <option>options ACPI_DEBUG</option> to your kernel config
2743 if <acronym>ACPI</acronym> is compiled into the kernel. You can
2744 add <option>ACPI_DEBUG=1</option> to your
2745 <filename>/etc/make.conf</filename> to enable it globally. If
2746 it is a module, you can recompile just your
2747 <filename>acpi.ko</filename> module as follows:</para>
2749 <screen>&prompt.root; <userinput>cd /sys/dev/acpica5
2750 && make clean &&
2751 make ACPI_DEBUG=1</userinput></screen>
2753 <para>Install <filename>acpi.ko</filename> in
2754 <filename role="directory">/boot/kernel</filename> and add your
2755 desired level and layer to <filename>loader.conf</filename>.
2756 This example enables debug messages for all
2757 <acronym>ACPI-CA</acronym> components and all
2758 <acronym>ACPI</acronym> hardware drivers
2759 (<acronym>CPU</acronym>, <acronym>LID</acronym>, etc.) It will
2760 only output error messages, the least verbose level.</para>
2762 <programlisting>debug.acpi.layer="ACPI_ALL_COMPONENTS ACPI_ALL_DRIVERS"
2763 debug.acpi.level="ACPI_LV_ERROR"</programlisting>
2765 <para>If the information you want is triggered by a specific event
2766 (say, a suspend and then resume), you can leave out changes to
2767 <filename>loader.conf</filename> and instead use
2768 <command>sysctl</command> to specify the layer and level after
2769 booting and preparing your system for the specific event. The
2770 <command>sysctl</command>s are named the same as the tunables
2771 in <filename>loader.conf</filename>.</para>
2774 <sect2 id="ACPI-References">
2775 <title>References</title>
2777 <para>More information about <acronym>ACPI</acronym> may be found
2778 in the following locations:</para>
2782 <para>The &a.freebsd.acpi; (This is FreeBSD-specific; posting
2783 &os; questions here may not generate much of an answer.)</para>
2787 <para>The <acronym>ACPI</acronym> Mailing List Archives (FreeBSD)
2788 <ulink url="http://lists.freebsd.org/pipermail/freebsd-acpi/"></ulink></para>
2792 <para>The old <acronym>ACPI</acronym> Mailing List Archives (FreeBSD)
2793 <ulink url="http://home.jp.FreeBSD.org/mail-list/acpi-jp/"></ulink></para>
2797 <para>The <acronym>ACPI</acronym> 2.0 Specification
2798 <ulink url="http://acpi.info/spec.htm"></ulink></para>
2802 <para>&os; Manual pages:
2805 &man.acpidb.8;</para>
2810 url="http://www.cpqlinux.com/acpi-howto.html#fix_broken_dsdt">
2811 <acronym>DSDT</acronym> debugging resource</ulink>.
2812 (Uses Compaq as an example but generally useful.)</para>
2822 sgml-declaration: "../chapter.decl"
2825 sgml-always-quote-attributes: t
2826 sgml-parent-document: ("../book.sgml" "part" "chapter")