41e7d4e0f7e0475eb697ce2b9a1cbbcd6b460bdc
[dragonfly.git] / en / books / handbook / config / chapter.sgml
1 <!--
2      The FreeBSD Documentation Project
3
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.12 2006/07/18 02:02:17 justin Exp $
6 -->
7
8 <chapter id="config-tuning">
9   <chapterinfo>
10     <authorgroup>
11       <author>
12         <firstname>Chern</firstname>
13         <surname>Lee</surname>
14         <contrib>Written by </contrib>
15       </author>
16     </authorgroup>
17     <authorgroup>
18       <author>
19         <firstname>Mike</firstname>
20         <surname>Smith</surname>
21         <contrib>Based on a tutorial written by </contrib>
22       </author>
23     </authorgroup>
24     <authorgroup>
25       <author>
26         <firstname>Matt</firstname>
27         <surname>Dillon</surname>
28         <contrib>Also based on tuning(7) written by </contrib>
29       </author>
30     </authorgroup>
31   </chapterinfo>
32
33   <title>Configuration and Tuning</title>
34
35   <sect1 id="config-synopsis">
36     <title>Synopsis</title>
37
38     <indexterm><primary>system configuration</primary></indexterm>
39     <indexterm><primary>system optimization</primary></indexterm>
40
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.
46       </para>
47
48     <para>After reading this chapter, you will know:
49
50       <itemizedlist>
51         <listitem>
52         <para>How to efficiently work with
53           file systems and swap partitions.</para>
54         </listitem>
55         <listitem>
56         <para>The basics of <filename>rc.conf</filename> configuration and
57           <filename>rc.d</filename> startup systems.</para>
58         </listitem>
59         <listitem>
60         <para>How to configure and test a network card.</para>
61         </listitem>
62         <listitem>
63         <para>How to configure virtual hosts on your network devices.</para>
64         </listitem>
65         <listitem>
66         <para>How to use the various configuration files in
67           <filename>/etc</filename>.</para>
68         </listitem>
69         <listitem>
70           <para>How to tune &os; using <command>sysctl</command>
71             variables.</para>
72         </listitem>
73         <listitem>
74         <para>How to tune disk performance and modify kernel
75           limitations.</para>
76         </listitem>
77       </itemizedlist>
78     </para>
79
80     <para>Before reading this chapter, you should:
81
82     <itemizedlist>
83       <listitem>
84         <para>Understand &unix; and &os; basics (<xref
85             linkend="basics">).</para>
86       </listitem>
87       <listitem>
88         <para>Be familiar with the basics of kernel configuration/compilation
89           (<xref linkend="kernelconfig">).</para>
90       </listitem>
91     </itemizedlist>
92     </para>
93   </sect1>
94
95   <sect1 id="configtuning-initial">
96     <title>Initial Configuration</title>
97
98     <sect2>
99       <title>Partition Layout</title>
100
101       <indexterm><primary>partition layout</primary></indexterm>
102       <indexterm>
103         <primary><filename>/etc</filename></primary>
104       </indexterm>
105       <indexterm>
106         <primary><filename>/var</filename></primary>
107       </indexterm>
108       <indexterm>
109         <primary><filename>/usr</filename></primary>
110       </indexterm>
111
112       <sect3>
113         <title>Base Partitions</title>
114
115         <para>When laying out file systems with &man.disklabel.8;
116           remember that hard
117           drives transfer data faster from the outer
118           tracks to the inner.
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>
125
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.
135           </para>
136
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>
141
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
145           hassle.</para>
146
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>
153 -->
154
155       </sect3>
156
157       <sect3 id="swap-design">
158         <title>Swap Partition</title>
159
160         <indexterm><primary>swap sizing</primary></indexterm>
161         <indexterm><primary>swap partition</primary></indexterm>
162
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&nbsp;megabytes of memory,
166           the swap file should be 256&nbsp;megabytes.  Systems with
167           less memory may perform better with more swap.
168           Less than 256&nbsp;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>
175
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
184           across disks.
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>
188       </sect3>
189
190       <sect3>
191         <title>Why Partition?</title>
192
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>
202
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
207           the disk's edge,
208           will
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>
218       </sect3>
219     </sect2>
220
221   </sect1>
222
223   <sect1 id="configtuning-core-configuration">
224     <title>Core Configuration</title>
225
226     <indexterm>
227       <primary>rc files</primary>
228       <secondary><filename>rc.conf</filename></secondary>
229     </indexterm>
230
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>
237
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>
245       file itself.</para>
246
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>
255
256     <para>As <filename>rc.conf</filename> is read by &man.sh.1; it is
257       trivial to achieve this.  For example:</para>
258
259     <itemizedlist>
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"
267         saver="daemon"
268         blanktime="100"</programlisting></listitem>
269     </itemizedlist>
270
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>
275
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>
280
281   </sect1>
282
283   <sect1 id="configtuning-appconfig">
284     <title>Application Configuration</title>
285
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>
291
292     <indexterm><primary>/usr/local/etc</primary></indexterm>
293
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>
298
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
302       are no existing
303       configuration files for the application, they will be created by
304       copying the <filename>.default</filename> files.</para>
305
306     <para>For example, consider the contents of the directory
307     <filename>/usr/local/etc/apache</filename>:</para>
308
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>
319
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>
323
324   </sect1>
325
326   <sect1 id="configtuning-starting-services">
327     <title>Starting Services</title>
328
329     <indexterm><primary>services</primary></indexterm>
330
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>
334
335     <indexterm><primary>/usr/local/etc/rc.d</primary></indexterm>
336
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>
349
350     <para>A generic startup script in
351       <filename>/usr/local/etc/rc.d</filename> looks like:</para>
352
353     <programlisting>#!/bin/sh
354 echo -n ' FooBar'
355
356 case "$1" in
357 start)
358         /usr/local/bin/foobar
359         ;;
360 stop)
361         kill -9 `cat /var/run/foobar.pid`
362         ;;
363 *)
364         echo "Usage: `basename $0` {start|stop}" >&2
365         exit 64
366         ;;
367 esac
368
369 exit 0
370     </programlisting>
371
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>
384
385     <screen>&prompt.root; <userinput>chmod 755 <replaceable>FooBar.sh</replaceable></userinput></screen>
386
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>
392
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>
400
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>
405     </note>
406
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>
412
413     <para>This takes advantage of a feature of &man.cron.8;: the
414       time specification may be replaced by <literal>@reboot</literal>,
415       which will
416       cause the job to be run when &man.cron.8; is started shortly after
417       system boot.</para>
418   </sect1>
419
420   <sect1 id="configtuning-cron">
421     <sect1info>
422       <authorgroup>
423         <author>
424         <firstname>Tom</firstname>
425         <surname>Rhodes</surname>
426         <contrib>Contributed by </contrib>
427         <!-- 20 May 2003 -->
428         </author>
429       </authorgroup>
430     </sect1info>
431     <title>Configuring the <command>cron</command> Utility</title>
432
433     <indexterm><primary>cron</primary>
434       <secondary>configuration</secondary></indexterm>
435
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>
444
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>
453
454     <note>
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>
458
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>
464     </note>
465
466     <para>Let us take a look at the <filename>/etc/crontab</filename> file
467       (the system crontab):</para>
468
469
470     <!-- todo: add up-to-date crontab -->
471     <programlisting># /etc/crontab - root's crontab for &os;
472 #
473 # <co id="co-comments">
474 #
475 SHELL=/bin/sh
476 PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin <co id="co-env">
477 HOME=/var/log
478 #
479 #
480 #minute hour    mday    month   wday    who     command <co id="co-field-descr">
481 #
482 #
483 */5     *       *       *       *       root    /usr/libexec/atrun <co id="co-main">
484 </programlisting>
485
486     <calloutlist>
487       <callout arearefs="co-comments">
488         <para>Like most &os; configuration files, the <literal>#</literal>
489           character represents a comment.  A comment can be placed in
490           the file as a reminder of what and why a desired action is performed.
491           Comments cannot be on the same line as a command or else they will
492           be interpreted as part of the command; they must be on a new line.
493           Blank lines are ignored.</para>
494       </callout>
495
496       <callout arearefs="co-env">
497         <para>First, the environment must be defined.  The equals
498           (<literal>=</literal>) character is used to define any environment
499           settings, as with this example where it is used for the <envar>SHELL</envar>,
500           <envar>PATH</envar>, and <envar>HOME</envar> options.  If the shell line is
501           omitted, <command>cron</command> will use the default, which is
502           <command>sh</command>.  If the <envar>PATH</envar> variable is
503           omitted, no default will be used and file locations will need to
504           be absolute.  If <envar>HOME</envar> is omitted, <command>cron</command>
505           will use the invoking users home directory.</para>
506       </callout>
507
508       <callout arearefs="co-field-descr">
509         <para>This line defines a total of seven fields.  Listed here are the
510           values <literal>minute</literal>, <literal>hour</literal>,
511           <literal>mday</literal>, <literal>month</literal>, <literal>wday</literal>,
512           <literal>who</literal>, and <literal>command</literal>.  These
513           are almost all self explanatory.  <literal>minute</literal> is the time in minutes the
514           command will be run.  <literal>hour</literal> is similar to the <literal>minute</literal> option, just in
515           hours.  <literal>mday</literal> stands for day of the month.  <literal>month</literal> is similar to <literal>hour</literal>
516           and <literal>minute</literal>, as it designates the month.  The <literal>wday</literal> option stands for
517           day of the week.  All these fields must be numeric values, and follow
518           the twenty-four hour clock.  The <literal>who</literal> field is special,
519           and only exists in the <filename>/etc/crontab</filename> file.
520           This field specifies which user the command should be run as.
521           When a user installs his or her <filename>crontab</filename> file, they
522           will not have this option. Finally, the <literal>command</literal> option is listed.
523           This is the last field, so naturally it should designate the command
524           to be executed.</para>
525       </callout>
526
527       <callout arearefs="co-main">
528         <para>This last line will define the values discussed above.  Notice here
529           we have a <literal>*/5</literal> listing, followed by several more
530           <literal>*</literal> characters.  These <literal>*</literal> characters
531           mean <quote>first-last</quote>, and can be interpreted as
532           <emphasis>every</emphasis> time.  So, judging by this line,
533           it is apparent that the <command>atrun</command> command is to be invoked by
534           <username>root</username> every five minutes regardless of what
535           day or month it is.  For more information on the <command>atrun</command> command,
536           see the &man.atrun.8; manual page.</para>
537
538         <para>Commands can have any number of flags passed to them; however,
539           commands which extend to multiple lines need to be broken with the backslash
540           <quote>\</quote> continuation character.</para>
541       </callout>
542     </calloutlist>
543
544     <para>This is the basic set up for every
545       <filename>crontab</filename> file, although there is one thing
546       different about this one.  Field number six, where we specified
547       the username, only exists in the system
548       <filename>/etc/crontab</filename> file.  This field should be
549       omitted for individual user <filename>crontab</filename>
550       files.</para>
551
552
553     <sect2 id="configtuning-installcrontab">
554       <title>Installing a Crontab</title>
555
556       <important>
557       <para>You must not use the procedure described here to
558         edit/install the system crontab. Simply use your favorite
559         editor: the <command>cron</command> utility will notice that the file
560         has changed and immediately begin using the updated version. 
561         If you use <command>crontab</command> to load the
562         <filename>/etc/crontab</filename> file you may get an error
563         like <errorname>root: not found</errorname> because of the 
564         system crontab's additional user field.</para>
565       </important>
566
567       <para>To install a freshly written user
568         <filename>crontab</filename>, first use your favorite editor to create
569         a file in the proper format, and then use the
570         <command>crontab</command> utility.  The most common usage
571         is:</para>
572
573       <screen>&prompt.user; <userinput>crontab crontab-file</userinput></screen>
574       
575       <para>In this example, <filename>crontab-file</filename> is the filename
576     of a <filename>crontab</filename> that was previously created.</para>
577
578       <para>There is also an option to list installed
579         <filename>crontab</filename> files: just pass the
580         <option>-l</option> option to <command>crontab</command> and look
581         over the output.</para>
582
583       <para>For users who wish to begin their own crontab file from scratch,
584         without the use of a template, the <command>crontab -e</command>
585         option is available.  This will invoke the selected editor
586         with an empty file.  When the file is saved, it will be
587         automatically installed by the <command>crontab</command> command.
588       </para>
589       
590       <para>If you later want to remove your user <filename>crontab</filename>
591         completely, use <command>crontab</command> with the <option>-r</option>
592         option.
593       </para>
594
595     </sect2>
596   </sect1>
597
598   <sect1 id="configtuning-rcNG">
599     <sect1info>
600       <authorgroup>
601         <author>
602          <firstname>Tom</firstname>
603          <surname>Rhodes</surname>
604          <contrib>Contributed by </contrib>
605          <!-- 16 May 2003 -->
606         </author>
607       </authorgroup>
608     </sect1info>
609
610     <title>Using rc under &os;</title>
611
612     <indexterm><primary>rcNG</primary></indexterm>
613
614     <para>&os; uses the &netbsd;
615       <filename>rc.d</filename> system for system initialization.
616       Users should notice the files listed in the
617       <filename>/etc/rc.d</filename> directory.  Many of these files
618       are for basic services which can be controlled with the
619       <option>start</option>, <option>stop</option>,
620       and <option>restart</option> options.
621       For instance, &man.sshd.8; can be restarted with the following
622       command:</para>
623
624     <screen>&prompt.root; <userinput>/etc/rc.d/sshd restart</userinput></screen>
625
626     <para>This procedure is similar for other services.  Of course,
627       services are usually started automatically as specified in
628       &man.rc.conf.5;.  For example, enabling the Network Address
629       Translation daemon at startup is as simple as adding the
630       following line to <filename>/etc/rc.conf</filename>:</para>
631
632     <programlisting>natd_enable="YES"</programlisting>
633
634     <para>If a <option>natd_enable="NO"</option> line is already
635        present, then simply change the <option>NO</option> to
636        <option>YES</option>.  The rc scripts will automatically load
637        any other dependent services during the next reboot, as
638        described below.</para>
639
640     <para>Since the <filename>rc.d</filename> system is primarily
641       intended to start/stop services at system startup/shutdown time,
642       the standard <option>start</option>,
643       <option>stop</option> and <option>restart</option> options will only
644       perform their action if the appropriate
645       <filename>/etc/rc.conf</filename> variables are set.  For
646       instance the above <command>sshd restart</command> command will
647       only work if <varname>sshd_enable</varname> is set to
648       <option>YES</option> in <filename>/etc/rc.conf</filename>.  To
649       <option>start</option>, <option>stop</option> or
650       <option>restart</option> a service regardless of the settings in
651       <filename>/etc/rc.conf</filename>, the commands should be
652       prefixed with <quote>force</quote>.  For instance to restart
653       <command>sshd</command> regardless of the current
654       <filename>/etc/rc.conf</filename> setting, execute the following
655       command:</para>
656
657     <screen>&prompt.root; <userinput>/etc/rc.d/sshd forcerestart</userinput></screen>
658
659     <para>It is easy to check if a service is enabled in
660       <filename>/etc/rc.conf</filename> by running the appropriate
661       <filename>rc.d</filename> script with the option
662       <option>rcvar</option>.  Thus, an administrator can check that
663       <command>sshd</command> is in fact enabled in
664       <filename>/etc/rc.conf</filename> by running:</para>
665
666     <screen>&prompt.root; <userinput>/etc/rc.d/sshd rcvar</userinput>
667 # sshd
668 $sshd_enable=YES</screen>
669
670     <note>
671       <para>The second line (<literal># sshd</literal>) is the output
672         from the <command>rc.d</command> script, not a
673         <username>root</username> prompt.</para>
674     </note>
675
676     <para>To determine if a service is running, a
677       <option>status</option> option is available.  For instance to
678       verify that <command>sshd</command> is actually started:</para>
679
680     <screen>&prompt.root; <userinput>/etc/rc.d/sshd status</userinput>
681 sshd is running as pid 433.</screen>
682
683     <para>It is also possible to <option>reload</option> a service.
684       This will attempt to send a signal to an individual service, forcing the
685       service to reload its configuration files.  In most cases this
686       means sending the service a <literal>SIGHUP</literal>
687       signal.</para>
688
689     <para>The <application>rcNG</application> structure is used both 
690       for network services and system initialization.  Some services are run 
691       only at boot; and the RCNG system is what triggers them.
692
693     <para>Many system services depend on other services to function
694       properly.  For example, NIS and other RPC-based services may
695       fail to start until after the <command>rpcbind</command>
696       (portmapper) service has started.  To resolve this issue,
697       information about dependencies and other meta-data is included
698       in the comments at the top of each startup script.  The
699       &man.rcorder.8; program is then used to parse these comments
700       during system initialization to determine the order in which
701       system services should be invoked to satisfy the dependencies.
702       The following words may be included at the top of each startup
703       file:</para>
704
705     <itemizedlist>
706       <listitem>
707         <para><literal>PROVIDE</literal>: Specifies the services this file provides.</para>
708       </listitem>
709
710       <listitem>
711         <para><literal>REQUIRE</literal>: Lists services which are required for this
712           service.  This file will run <emphasis>after</emphasis>
713           the specified services.</para>
714       </listitem>
715
716       <listitem>
717         <para><literal>BEFORE</literal>: Lists services which depend on this service.
718           This file will run <emphasis>before</emphasis>
719           the specified services.</para>
720       </listitem>
721
722       <listitem>
723         <para>KEYWORD: When &man.rcorder.8; uses the <option>-k</option>
724          option, then only the rc.d files matching this keyword are used.
725
726          <footnote>
727            <para>Previously this was used to define *BSD dependent features.
728            </para></footnote>
729
730          For example, when using <option>-k shutdown</option>, only the
731          <filename>rc.d</filename> scripts defining the
732          <literal>shutdown</literal> keyword are used.
733         </para>
734
735         <para>With the <option>-s</option> option, &man.rcorder.8 will
736         skip any <filename>rc.d</filename> script defining the
737         corresponding keyword to skip. For example, scripts defining the
738         <literal>nostart</literal> keyword are skipped at boot time.</para>
739       </listitem>
740     </itemizedlist>
741
742     <para>By using this method, an administrator can easily control system
743       services without the hassle of <quote>runlevels</quote> like
744       some other &unix; operating systems.</para>
745
746     <para>Additional information about the &os; 
747       <filename>rc.d</filename> system can be found in the &man.rc.8;,
748       &man.rc.conf.5;, and &man.rc.subr.8; manual pages.</para>
749   </sect1>
750
751   <sect1 id="config-network-setup">
752     <sect1info>
753       <authorgroup>
754         <author>
755          <firstname>Marc</firstname>
756          <surname>Fonvieille</surname>
757          <contrib>Contributed by </contrib>
758          <!-- 6 October 2002 -->
759         </author>
760       </authorgroup>
761     </sect1info>
762
763     <title>Setting Up Network Interface Cards</title>
764
765     <indexterm><primary>network card configuration</primary></indexterm>
766
767     <para>Nowadays we can not think about a computer without thinking
768       about a network connection.  Adding and configuring a network
769       card is a common task for any &os; administrator.</para>
770
771     <sect2>
772       <title>Locating the Correct Driver</title>
773
774       <indexterm>
775         <primary>network card configuration</primary>
776         <secondary>locating the driver</secondary>
777       </indexterm>
778
779       <para>Before you begin, you should know the model of the card
780         you have, the chip it uses, and whether it is a PCI or ISA card.
781         &os; supports a wide variety of both PCI and ISA cards.
782         Check the Hardware Compatibility List for your release to see
783         if your card is supported.</para>
784
785       <para>Once you are sure your card is supported, you need
786         to determine the proper driver for the card.  The file
787         <filename>/usr/src/sys/i386/conf/LINT</filename> will give you
788         the list of network interfaces drivers with some information
789         about the supported chipsets/cards.  If you have doubts about
790         which driver is the correct one, read the manual page of the
791         driver.  The manual page will give you more information about
792         the supported hardware and even the possible problems that
793         could occur.</para>
794
795       <para>If you own a common card, most of the time you will not
796         have to look very hard for a driver.  Drivers for common
797         network cards are present in the <filename>GENERIC</filename>
798         kernel, so your card should show up during boot, like so:</para>
799
800 <screen>dc0: &lt;82c169 PNIC 10/100BaseTX&gt; port 0xa000-0xa0ff mem 0xd3800000-0xd38
801 000ff irq 15 at device 11.0 on pci0
802 dc0: Ethernet address: 00:a0:cc:da:da:da
803 miibus0: &lt;MII bus&gt; on dc0
804 ukphy0: &lt;Generic IEEE 802.3u media interface&gt; on miibus0
805 ukphy0:  10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto
806 dc1: &lt;82c169 PNIC 10/100BaseTX&gt; port 0x9800-0x98ff mem 0xd3000000-0xd30
807 000ff irq 11 at device 12.0 on pci0
808 dc1: Ethernet address: 00:a0:cc:da:da:db
809 miibus1: &lt;MII bus&gt; on dc1
810 ukphy1: &lt;Generic IEEE 802.3u media interface&gt; on miibus1
811 ukphy1:  10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto</screen>
812
813       <para>In this example, we see that two cards using the &man.dc.4;
814         driver are present on the system.</para>
815
816       <para>To use your network card, you will need to load the proper
817         driver.  This may be accomplished in one of two ways.  The
818         easiest way is to simply load a kernel module for your network
819         card with &man.kldload.8;.  A module is not available for all
820         network card drivers (ISA cards and cards using the &man.ed.4;
821         driver, for example).  Alternatively, you may statically compile
822         the support for your card into your kernel.  Check
823         <filename>/usr/src/sys/i386/conf/LINT</filename> and the
824         manual page of the driver to know what to add in your kernel
825         configuration file.  For more information about recompiling your
826         kernel, please see <xref linkend="kernelconfig">.  If your card
827         was detected at boot by your kernel (<filename>GENERIC</filename>)
828         you do not have to build a new kernel.</para>
829     </sect2>
830
831     <sect2>
832       <title>Configuring the Network Card</title>
833
834       <indexterm>
835         <primary>Network card configuration</primary>
836         <secondary>configuration</secondary>
837       </indexterm>
838
839       <para>Once the right driver is loaded for the network card, the
840         card needs to be configured. As with many other things, the
841         network card may have been configured at installation time.</para>
842
843       <para>To display the configuration for the network interfaces on
844         your system, enter the following command:</para>
845
846 <screen>&prompt.user; <userinput>ifconfig</userinput>
847 dc0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
848         inet 192.168.1.3 netmask 0xffffff00 broadcast 192.168.1.255
849         ether 00:a0:cc:da:da:da
850         media: Ethernet autoselect (100baseTX &lt;full-duplex&gt;)
851         status: active
852 dc1: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
853         inet 10.0.0.1 netmask 0xffffff00 broadcast 10.0.0.255
854         ether 00:a0:cc:da:da:db
855         media: Ethernet 10baseT/UTP
856         status: no carrier
857 lp0: flags=8810&lt;POINTOPOINT,SIMPLEX,MULTICAST&gt; mtu 1500
858 lo0: flags=8049&lt;UP,LOOPBACK,RUNNING,MULTICAST&gt; mtu 16384
859         inet 127.0.0.1 netmask 0xff000000
860 tun0: flags=8010&lt;POINTOPOINT,MULTICAST&gt; mtu 1500</screen>
861
862       <note>
863         <para>Note that entries concerning IPv6
864           (<literal>inet6</literal> etc.) were omitted in this
865           example.</para>
866       </note>
867
868       <para>In this example, the following devices were
869         displayed:</para>
870
871       <itemizedlist>
872         <listitem>
873           <para><devicename>dc0</devicename>: The first Ethernet
874             interface</para>
875         </listitem>
876
877         <listitem>
878           <para><devicename>dc1</devicename>: The second Ethernet
879             interface</para>
880         </listitem>
881
882         <listitem>
883           <para><devicename>lp0</devicename>: The parallel port
884             interface</para>
885         </listitem>
886
887         <listitem>
888           <para><devicename>lo0</devicename>: The loopback device</para>
889         </listitem>
890
891         <listitem>
892           <para><devicename>tun0</devicename>: The tunnel device used by
893             <application>ppp</application></para>
894         </listitem>
895       </itemizedlist>
896
897       <para>&os; uses the driver name followed by the order in
898         which one the card is detected at the kernel boot to name the
899         network card, starting the count at zero.  For example, 
900         <devicename>sis2</devicename> would be the third network card 
901         on the system using the &man.sis.4; driver.</para>
902
903       <para>In this example, the <devicename>dc0</devicename> device is
904         up and running.  The key indicators are:</para>
905
906       <orderedlist>
907         <listitem>
908           <para><literal>UP</literal> means that the card is configured
909             and ready.</para>
910         </listitem>
911
912         <listitem>
913           <para>The card has an Internet (<literal>inet</literal>)
914             address (in this case
915             <hostid role="ipaddr">192.168.1.3</hostid>).</para>
916         </listitem>
917
918         <listitem>
919           <para>It has a valid subnet mask (<literal>netmask</literal>;
920             <hostid role="netmask">0xffffff00</hostid> is the same as
921             <hostid role="netmask">255.255.255.0</hostid>).</para>
922         </listitem>
923
924         <listitem>
925           <para>It has a valid broadcast address (in this case,
926             <hostid role="ipaddr">192.168.1.255</hostid>).</para>
927         </listitem>
928
929         <listitem>
930           <para>The MAC address of the card (<literal>ether</literal>)
931             is <hostid role="mac">00:a0:cc:da:da:da</hostid></para>
932         </listitem>
933
934         <listitem>
935           <para>The physical media selection is on autoselection mode
936             (<literal>media: Ethernet autoselect (100baseTX
937             &lt;full-duplex&gt;)</literal>).  We see that
938             <devicename>dc1</devicename> was configured to run with
939             <literal>10baseT/UTP</literal> media.  For more
940             information on available media types for a driver, please
941             refer to its manual page.</para>
942         </listitem>
943
944         <listitem>
945           <para>The status of the link (<literal>status</literal>)
946             is <literal>active</literal>, i.e. the carrier is detected.
947             For <devicename>dc1</devicename>, we see
948             <literal>status: no carrier</literal>.  This is normal when
949             an Ethernet cable is not plugged into the card.</para>
950         </listitem>
951       </orderedlist>
952
953       <para>If the &man.ifconfig.8; output had shown something similar
954         to:</para>
955
956 <screen>dc0: flags=8843&lt;BROADCAST,SIMPLEX,MULTICAST&gt; mtu 1500
957                 ether 00:a0:cc:da:da:da</screen>
958
959       <para>it would indicate the card has not been configured.</para>
960
961       <para>To configure your card, you need <username>root</username>
962         privileges.  The network card configuration can be done from the
963         command line with &man.ifconfig.8; as root.</para>
964         
965 <screen>
966 &prompt.root; <userinput>ifconfig dc0 inet 192.168.1.3 netmask 255.255.255.0</userinput>
967 </screen>
968       
969       
970       <para>Manually configuring the care has the disadvantage that you 
971         would have to do it after each reboot of the system.  The file
972         <filename>/etc/rc.conf</filename> is where to add the network
973         card's configuration.</para>
974
975       <para>Open <filename>/etc/rc.conf</filename> in your favorite
976         editor.  You need to add a line for each network card present on
977         the system, for example in our case, we added these lines:</para>
978
979 <programlisting>ifconfig_dc0="inet 192.168.1.3 netmask 255.255.255.0"
980 ifconfig_dc1="inet 10.0.0.1 netmask 255.255.255.0 media 10baseT/UTP"</programlisting>
981
982       <para>You have to replace <devicename>dc0</devicename>,
983         <devicename>dc1</devicename>, and so on, with
984         the correct device for your cards, and the addresses with the
985         proper ones.  You should read the card driver and
986         &man.ifconfig.8; manual pages for more details about the allowed
987         options and also &man.rc.conf.5; manual page for more
988         information on the syntax of
989         <filename>/etc/rc.conf</filename>.</para>
990
991       <para>If you configured the network during installation, some
992         lines about the network card(s) may be already present.  Double
993         check <filename>/etc/rc.conf</filename> before adding any
994         lines.</para>
995
996       <para>You will also have to edit the file
997         <filename>/etc/hosts</filename> to add the names and the IP
998         addresses of various machines of the LAN, if they are not already
999         there.  For more information please refer to &man.hosts.5;
1000         and to <filename>/usr/share/examples/etc/hosts</filename>.</para>
1001     </sect2>
1002
1003     <sect2>
1004       <title>Testing and Troubleshooting</title>
1005
1006       <para>Once you have made the necessary changes in
1007         <filename>/etc/rc.conf</filename>, you should reboot your
1008         system.  This will allow the change(s) to the interface(s) to
1009         be applied, and verify that the system restarts without any
1010         configuration errors.</para>
1011
1012       <para>Once the system has been rebooted, you should test the
1013         network interfaces.</para>
1014
1015       <sect3>
1016         <title>Testing the Ethernet Card</title>
1017
1018         <indexterm>
1019           <primary>network card configuration</primary>
1020           <secondary>testing the card</secondary>
1021         </indexterm>
1022
1023         <para>To verify that an Ethernet card is configured correctly,
1024           you have to try two things.  First, ping the interface itself,
1025           and then ping another machine on the LAN.</para>
1026
1027         <para>First test the local interface:</para>
1028
1029 <screen>&prompt.user; <userinput>ping -c5 192.168.1.3</userinput>
1030 PING 192.168.1.3 (192.168.1.3): 56 data bytes
1031 64 bytes from 192.168.1.3: icmp_seq=0 ttl=64 time=0.082 ms
1032 64 bytes from 192.168.1.3: icmp_seq=1 ttl=64 time=0.074 ms
1033 64 bytes from 192.168.1.3: icmp_seq=2 ttl=64 time=0.076 ms
1034 64 bytes from 192.168.1.3: icmp_seq=3 ttl=64 time=0.108 ms
1035 64 bytes from 192.168.1.3: icmp_seq=4 ttl=64 time=0.076 ms
1036
1037 --- 192.168.1.3 ping statistics ---
1038 5 packets transmitted, 5 packets received, 0% packet loss
1039 round-trip min/avg/max/stddev = 0.074/0.083/0.108/0.013 ms</screen>
1040
1041         <para>Now we have to ping another machine on the LAN:</para>
1042
1043 <screen>&prompt.user; <userinput>ping -c5 192.168.1.2</userinput>
1044 PING 192.168.1.2 (192.168.1.2): 56 data bytes
1045 64 bytes from 192.168.1.2: icmp_seq=0 ttl=64 time=0.726 ms
1046 64 bytes from 192.168.1.2: icmp_seq=1 ttl=64 time=0.766 ms
1047 64 bytes from 192.168.1.2: icmp_seq=2 ttl=64 time=0.700 ms
1048 64 bytes from 192.168.1.2: icmp_seq=3 ttl=64 time=0.747 ms
1049 64 bytes from 192.168.1.2: icmp_seq=4 ttl=64 time=0.704 ms
1050
1051 --- 192.168.1.2 ping statistics ---
1052 5 packets transmitted, 5 packets received, 0% packet loss
1053 round-trip min/avg/max/stddev = 0.700/0.729/0.766/0.025 ms</screen>
1054
1055         <para>You could also use the machine name instead of
1056           <hostid role="ipaddr">192.168.1.2</hostid> if you have set up the
1057           <filename>/etc/hosts</filename> file.</para>
1058       </sect3>
1059
1060       <sect3>
1061         <title>Troubleshooting</title>
1062
1063       <indexterm>
1064         <primary>network card configuration</primary>
1065         <secondary>troubleshooting</secondary>
1066       </indexterm>
1067
1068       <para>Troubleshooting hardware and software configurations is always
1069         a pain, and a pain which can be alleviated by checking the simple
1070         things first.  Is your network cable plugged in?  Have you properly
1071         configured the network services?  Did you configure the firewall
1072         correctly?  Is the card you are using supported by &os;?  Always
1073         check the hardware notes before sending off a bug report.  Update
1074         your version of &os; to the latest PREVIEW version.  Check the
1075         mailing list archives, or perhaps search the Internet.</para>
1076
1077       <para>If the card works, yet performance is poor, it would be
1078         worthwhile to read over the &man.tuning.7; manual page.  You
1079         can also check the network configuration as incorrect network
1080         settings can cause slow connections.</para>
1081
1082       <para>Some users experience one or two <quote>device
1083         timeouts</quote>, which is normal for some cards.  If they
1084         continue, or are bothersome, you may wish to be sure the
1085         device is not conflicting with another device.  Double check
1086         the cable connections.  Perhaps you may just need to get
1087         another card.</para>
1088
1089       <para>At times, users see a few <errorname>watchdog timeout</errorname>
1090         errors.  The first thing to do here is to check your network
1091         cable. Many cards require a PCI slot which supports Bus
1092         Mastering. On some old motherboards, only one PCI slot allows
1093         it (usually slot 0). Check the network card and the
1094         motherboard documentation to determine if that may be the
1095         problem.</para>
1096
1097       <para><errorname>No route to host</errorname> messages occur if the
1098         system is unable to route a packet to the destination host.
1099         This can happen if no default route is specified, or if a
1100         cable is unplugged.  Check the output of <command>netstat
1101         -rn</command> and make sure there is a valid route to the host
1102         you are trying to reach.  If there is not, read on to <xref
1103         linkend="advanced-networking">.</para>
1104
1105       <para><errorname>ping: sendto: Permission denied</errorname> error
1106         messages are often caused by a misconfigured firewall.  If
1107         <command>ipfw</command> is enabled in the kernel but no rules
1108         have been defined, then the default policy is to deny all
1109         traffic, even ping requests!  Read on to <xref
1110         linkend="firewalls"> for more information.</para>
1111
1112       <para>Sometimes performance of the card is poor, or below average.
1113         In these cases it is best to set the media selection mode
1114         from <literal>autoselect</literal> to the correct media selection.
1115         While this usually works for most hardware, it may not resolve
1116         this issue for everyone.  Again, check all the network settings,
1117         and read over the &man.tuning.7; manual page.</para>
1118
1119       </sect3>
1120     </sect2>
1121   </sect1>
1122
1123   <sect1 id="configtuning-virtual-hosts">
1124     <title>Virtual Hosts</title>
1125
1126     <indexterm><primary>virtual hosts</primary></indexterm>
1127     <indexterm><primary>IP aliases</primary></indexterm>
1128
1129     <para>A very common use of &os; is virtual site hosting, where
1130       one server appears to the network as many servers.  This is
1131       achieved by assigning multiple network addresses to a single
1132       interface.</para>
1133
1134     <para>A given network interface has one <quote>real</quote> address,
1135       and may have any number of <quote>alias</quote> addresses.
1136       These aliases are
1137       normally added by placing alias entries in
1138       <filename>/etc/rc.conf</filename>.</para>
1139
1140     <para>An alias entry for the interface <devicename>fxp0</devicename>
1141       looks like:</para>
1142
1143 <programlisting>ifconfig_fxp0_alias0="inet xxx.xxx.xxx.xxx netmask xxx.xxx.xxx.xxx"</programlisting>
1144
1145     <para>Note that alias entries must start with 
1146       <literal>alias0</literal> and proceed upwards in order, (for example, 
1147       <literal>_alias1</literal>, <literal>_alias2</literal>, and so on).
1148       The configuration process will stop at the first missing number.
1149     </para>
1150
1151     <para>The calculation of alias netmasks is important, but
1152       fortunately quite simple.  For a given interface, there must be
1153       one address which correctly represents the network's netmask.
1154       Any other addresses which fall within this network must have a
1155       netmask of all <literal>1</literal>s (expressed as either
1156       <hostid role="netmask">255.255.255.255</hostid> or 
1157       <hostid role="netmask">0xffffffff</hostid>).
1158     </para>
1159
1160     <para>For example, consider the case where the
1161       <devicename>fxp0</devicename> interface is
1162       connected to two networks, the <hostid role="ipaddr">10.1.1.0</hostid>
1163       network with a netmask of <hostid role="netmask">255.255.255.0</hostid>
1164       and the <hostid role="ipaddr">202.0.75.16</hostid> network with
1165       a netmask of <hostid role="netmask">255.255.255.240</hostid>.
1166       We want the system to appear at <hostid role="ipaddr">10.1.1.1</hostid>
1167       through <hostid role="ipaddr">10.1.1.5</hostid> and at
1168       <hostid role="ipaddr">202.0.75.17</hostid> through
1169       <hostid role="ipaddr">202.0.75.20</hostid>.  As noted above, only the
1170       first address in a given network range (in this case,
1171       <hostid role="ipaddr">10.0.1.1</hostid> and
1172       <hostid role="ipaddr">202.0.75.17</hostid>) should have a real
1173       netmask; all the rest (<hostid role="ipaddr">10.1.1.2</hostid>
1174       through <hostid role="ipaddr">10.1.1.5</hostid> and
1175       <hostid role="ipaddr">202.0.75.18</hostid> through
1176       <hostid role="ipaddr">202.0.75.20</hostid>) must be configured with a
1177       netmask of <hostid role="netmask">255.255.255.255</hostid>.</para>
1178
1179     <para>The following entries configure the adapter correctly for
1180       this arrangement:</para>
1181
1182 <programlisting> ifconfig_fxp0="inet 10.1.1.1 netmask 255.255.255.0"
1183  ifconfig_fxp0_alias0="inet 10.1.1.2 netmask 255.255.255.255"
1184  ifconfig_fxp0_alias1="inet 10.1.1.3 netmask 255.255.255.255"
1185  ifconfig_fxp0_alias2="inet 10.1.1.4 netmask 255.255.255.255"
1186  ifconfig_fxp0_alias3="inet 10.1.1.5 netmask 255.255.255.255"
1187  ifconfig_fxp0_alias4="inet 202.0.75.17 netmask 255.255.255.240"
1188  ifconfig_fxp0_alias5="inet 202.0.75.18 netmask 255.255.255.255"
1189  ifconfig_fxp0_alias6="inet 202.0.75.19 netmask 255.255.255.255"
1190  ifconfig_fxp0_alias7="inet 202.0.75.20 netmask 255.255.255.255"</programlisting>
1191
1192   </sect1>
1193
1194   <sect1 id="configtuning-configfiles">
1195     <title>Configuration Files</title>
1196
1197     <sect2>
1198       <title><filename>/etc</filename> Layout</title>
1199       <para>There are a number of directories in which configuration
1200         information is kept.  These include:</para>
1201
1202       <informaltable frame="none">
1203         <tgroup cols="2">
1204       <colspec colwidth="1*">
1205       <colspec colwidth="2*">
1206           <tbody>
1207             <row>
1208               <entry><filename>/etc</filename></entry>
1209               <entry>Generic system configuration information; data here is
1210                 system-specific.</entry>
1211             </row>
1212             <row>
1213               <entry><filename>/etc/defaults</filename></entry>
1214               <entry>Default versions of system configuration files.</entry>
1215             </row>
1216             <row>
1217               <entry><filename>/etc/mail</filename></entry>
1218               <entry>Extra &man.sendmail.8; configuration, other
1219                 MTA configuration files.
1220               </entry>
1221             </row>
1222             <row>
1223               <entry><filename>/etc/ppp</filename></entry>
1224               <entry>Configuration for both user- and kernel-ppp programs.
1225               </entry>
1226             </row>
1227             <row>
1228               <entry><filename>/etc/namedb</filename></entry>
1229               <entry>Default location for &man.named.8; data.  Normally
1230                 <filename>named.conf</filename> and zone files are stored
1231                 here.</entry>
1232             </row>
1233             <row>
1234               <entry><filename>/usr/local/etc</filename></entry>
1235               <entry>Configuration files for installed applications.
1236                 May contain per-application subdirectories.</entry>
1237             </row>
1238             <row>
1239               <entry><filename>/usr/local/etc/rc.d</filename></entry>
1240               <entry>Start/stop scripts for installed applications.</entry>
1241             </row>
1242             <row>
1243               <entry><filename>/var/db</filename></entry>
1244               <entry>Automatically generated system-specific database files,
1245                  such as the package database, the locate database, and so
1246                  on</entry>
1247             </row>
1248           </tbody>
1249         </tgroup>
1250       </informaltable>
1251     </sect2>
1252
1253     <sect2>
1254       <title>Hostnames</title>
1255
1256       <indexterm><primary>hostname</primary></indexterm>
1257       <indexterm><primary>DNS</primary></indexterm>
1258
1259       <sect3>
1260         <title><filename>/etc/resolv.conf</filename></title>
1261
1262         <indexterm>
1263           <primary><filename>resolv.conf</filename></primary>
1264         </indexterm>
1265
1266         <para><filename>/etc/resolv.conf</filename> dictates how &os;'s
1267           resolver accesses the Internet Domain Name System (DNS).</para>
1268
1269         <para>The most common entries to <filename>resolv.conf</filename> are:
1270         </para>
1271
1272         <informaltable frame="none">
1273           <tgroup cols="2">
1274       <colspec colwidth="1*">
1275       <colspec colwidth="2*">
1276             <tbody>
1277               <row>
1278                 <entry><literal>nameserver</literal></entry>
1279                 <entry>The IP address of a name server the resolver
1280                   should query.  The servers are queried in the order
1281                   listed with a maximum of three.</entry>
1282               </row>
1283               <row>
1284                 <entry><literal>search</literal></entry>
1285                 <entry>Search list for hostname lookup.  This is normally
1286                   determined by the domain of the local hostname.</entry>
1287               </row>
1288               <row>
1289                 <entry><literal>domain</literal></entry>
1290                 <entry>The local domain name.</entry>
1291               </row>
1292             </tbody>
1293           </tgroup>
1294         </informaltable>
1295
1296         <para>A typical <filename>resolv.conf</filename>:</para>
1297
1298         <programlisting>search example.com
1299 nameserver 147.11.1.11
1300 nameserver 147.11.100.30</programlisting>
1301
1302         <note><para>Only one of the <literal>search</literal> and
1303           <literal>domain</literal> options should be used.</para></note>
1304
1305         <para>If you are using DHCP, &man.dhclient.8; usually rewrites
1306           <filename>resolv.conf</filename> with information received from the
1307           DHCP server.</para>
1308       </sect3>
1309
1310       <sect3>
1311         <title><filename>/etc/hosts</filename></title>
1312
1313         <indexterm><primary>hosts</primary></indexterm>
1314
1315         <para><filename>/etc/hosts</filename> is a simple text
1316           database reminiscent of the old Internet.  It works in
1317           conjunction with DNS and NIS providing name to IP address
1318           mappings.  Local computers connected via a LAN can be placed
1319           in here for simplistic naming purposes instead of setting up
1320           a &man.named.8; server.  Additionally,
1321           <filename>/etc/hosts</filename> can be used to provide a
1322           local record of Internet names, reducing the need to query
1323           externally for commonly accessed names.</para>
1324
1325         <programlisting># 
1326 #
1327 # Host Database
1328 # This file should contain the addresses and aliases
1329 # for local hosts that share this file.
1330 # In the presence of the domain name service or NIS, this file may
1331 # not be consulted at all; see /etc/nsswitch.conf for the resolution order.
1332 #
1333 #
1334 ::1                     localhost localhost.my.domain myname.my.domain
1335 127.0.0.1               localhost localhost.my.domain myname.my.domain
1336
1337 #
1338 # Imaginary network.
1339 #10.0.0.2               myname.my.domain myname
1340 #10.0.0.3               myfriend.my.domain myfriend
1341 #
1342 # According to RFC 1918, you can use the following IP networks for
1343 # private nets which will never be connected to the Internet:
1344 #
1345 #       10.0.0.0        -   10.255.255.255
1346 #       172.16.0.0      -   172.31.255.255
1347 #       192.168.0.0     -   192.168.255.255
1348 #
1349 # In case you want to be able to connect to the Internet, you need
1350 # real official assigned numbers.  PLEASE PLEASE PLEASE do not try
1351 # to invent your own network numbers but instead get one from your
1352 # network provider (if any) or from the Internet Registry (ftp to
1353 # rs.internic.net, directory `/templates').
1354 #</programlisting>
1355
1356         <para><filename>/etc/hosts</filename> takes on the simple format
1357           of:</para>
1358
1359         <programlisting>[Internet address] [official hostname] [alias1] [alias2] ...</programlisting>
1360
1361         <para>For example:</para>
1362
1363         <programlisting>10.0.0.1 myRealHostname.example.com myRealHostname foobar1 foobar2</programlisting>
1364
1365         <para>Consult &man.hosts.5; for more information.</para>
1366       </sect3>
1367     </sect2>
1368
1369     <sect2>
1370       <title>Log File Configuration</title>
1371
1372       <indexterm><primary>log files</primary></indexterm>
1373
1374       <sect3>
1375         <title><filename>syslog.conf</filename></title>
1376
1377         <indexterm><primary>syslog.conf</primary></indexterm>
1378
1379         <para><filename>syslog.conf</filename> is the configuration file
1380           for the &man.syslogd.8; program.  It indicates which types
1381           of <command>syslog</command> messages are logged to particular
1382           log files.</para>
1383
1384         <programlisting># 
1385 #
1386 #       Spaces ARE valid field separators in this file. However,
1387 #       other *nix-like systems still insist on using tabs as field
1388 #       separators. If you are sharing this file between systems, you
1389 #       may want to use only tabs as field separators here.
1390 #       Consult the syslog.conf(5) manual page.
1391 *.err;kern.debug;auth.notice;mail.crit          /dev/console
1392 *.notice;kern.debug;lpr.info;mail.crit;news.err /var/log/messages
1393 security.*                                      /var/log/security
1394 mail.info                                       /var/log/maillog
1395 lpr.info                                        /var/log/lpd-errs
1396 cron.*                                          /var/log/cron
1397 *.err                                           root
1398 *.notice;news.err                               root
1399 *.alert                                         root
1400 *.emerg                                         *
1401 # uncomment this to log all writes to /dev/console to /var/log/console.log
1402 #console.info                                   /var/log/console.log
1403 # uncomment this to enable logging of all log messages to /var/log/all.log
1404 #*.*                                            /var/log/all.log
1405 # uncomment this to enable logging to a remote log host named loghost
1406 #*.*                                            @loghost
1407 # uncomment these if you're running inn
1408 # news.crit                                     /var/log/news/news.crit
1409 # news.err                                      /var/log/news/news.err
1410 # news.notice                                   /var/log/news/news.notice
1411 !startslip
1412 *.*                                             /var/log/slip.log
1413 !ppp
1414 *.*                                             /var/log/ppp.log</programlisting>
1415
1416 <!-- todo: reed: this should be documented in book -->
1417         <para>Consult the &man.syslog.conf.5; manual page for more
1418           information.</para>
1419       </sect3>
1420
1421       <sect3>
1422         <title><filename>newsyslog.conf</filename></title>
1423
1424         <indexterm><primary>newsyslog.conf</primary></indexterm>
1425
1426         <para><filename>newsyslog.conf</filename> is the configuration
1427           file for &man.newsyslog.8;, a program that is normally scheduled
1428           to run by &man.cron.8;.  &man.newsyslog.8; determines when log
1429           files require archiving or rearranging.
1430           <filename>logfile</filename> is moved to
1431           <filename>logfile.0</filename>, <filename>logfile.0</filename>
1432           is moved to <filename>logfile.1</filename>, and so on.
1433           Alternatively, the log files may be archived in &man.gzip.1; format
1434           causing them to be named: <filename>logfile.0.gz</filename>,
1435           <filename>logfile.1.gz</filename>, and so on.</para>
1436
1437         <para><filename>newsyslog.conf</filename> indicates which log
1438           files are to be managed, how many are to be kept, and when
1439           they are to be touched.  Log files can be rearranged and/or
1440           archived when they have either reached a certain size, or at a
1441           certain periodic time/date.</para>
1442
1443         <programlisting># configuration file for newsyslog
1444
1445 #
1446 # filename          [owner:group]    mode count size when [ZB] [/pid_file] [sig_num]
1447 /var/log/cron                           600  3     100  *     Z
1448 /var/log/amd.log                        644  7     100  *     Z
1449 /var/log/kerberos.log                   644  7     100  *     Z
1450 /var/log/lpd-errs                       644  7     100  *     Z
1451 /var/log/maillog                        644  7     *    @T00  Z
1452 /var/log/sendmail.st                    644  10    *    168   B
1453 /var/log/messages                       644  5     100  *     Z
1454 /var/log/all.log                        600  7     *    @T00  Z
1455 /var/log/slip.log                       600  3     100  *     Z
1456 /var/log/ppp.log                        600  3     100  *     Z
1457 /var/log/security                       600  10    100  *     Z
1458 /var/log/wtmp                           644  3     *    @01T05 B
1459 /var/log/daily.log                      640  7     *    @T00  Z
1460 /var/log/weekly.log                     640  5     1    $W6D0 Z
1461 /var/log/monthly.log                    640  12    *    $M1D0 Z
1462 /var/log/console.log                    640  5     100  *     Z</programlisting>
1463
1464 <!-- todo: reed: this should be documented in book -->
1465         <para>Consult the &man.newsyslog.8; manual page for more
1466           information.</para>
1467       </sect3>
1468     </sect2>
1469
1470     <sect2 id="configtuning-sysctlconf">
1471       <title><filename>sysctl.conf</filename></title>
1472
1473       <indexterm><primary>sysctl.conf</primary></indexterm>
1474       <indexterm><primary>sysctl</primary></indexterm>
1475
1476       <para><filename>sysctl.conf</filename> looks much like
1477         <filename>rc.conf</filename>.  Values are set in a
1478         <literal>variable=value</literal>
1479         form.  The specified values are set after the system goes into
1480         multi-user mode.  Not all variables are settable in this mode.</para>
1481
1482       <para>A sample <filename>sysctl.conf</filename> turning off logging
1483         of fatal signal exits and letting Linux programs know they are really
1484         running under &os;:</para>
1485
1486       <programlisting>kern.logsigexit=0       # Do not log fatal signal exits (e.g. sig 11)
1487 compat.linux.osname=&os;
1488 <!-- todo: reed: check this -->
1489 compat.linux.osrelease=4.3-STABLE</programlisting>
1490     </sect2>
1491   </sect1>
1492
1493   <sect1 id="configtuning-sysctl">
1494     <title>Tuning with sysctl</title>
1495
1496     <indexterm><primary>sysctl</primary></indexterm>
1497     <indexterm>
1498       <primary>tuning</primary>
1499       <secondary>with sysctl</secondary>
1500     </indexterm>
1501
1502     <para>&man.sysctl.8; is an interface that allows you to make changes
1503       to a running &os; system.  This includes many advanced
1504       options of the TCP/IP stack and virtual memory system that can
1505       dramatically improve performance for an experienced system
1506       administrator.  Over five hundred system variables can be read
1507       and set using &man.sysctl.8;.</para>
1508
1509     <para>At its core, &man.sysctl.8; serves two functions: to read and
1510       to modify system settings.</para>
1511
1512     <para>To view all readable variables:</para>
1513
1514     <screen>&prompt.user; <userinput>sysctl -a</userinput></screen>
1515
1516     <para>To read a particular variable, for example,
1517       <varname>kern.maxproc</varname>:</para>
1518
1519     <screen>&prompt.user; <userinput>sysctl kern.maxproc</userinput>
1520 kern.maxproc: 1044</screen>
1521
1522     <para>To set a particular variable, use the intuitive
1523       <replaceable>variable</replaceable>=<replaceable>value</replaceable>
1524       syntax:</para>
1525
1526     <screen>&prompt.root; <userinput>sysctl kern.maxfiles=5000</userinput>
1527 kern.maxfiles: 2088 -> 5000</screen>
1528
1529     <para>Settings of sysctl variables are usually either strings,
1530       numbers, or booleans (a  boolean being <literal>1</literal> for yes
1531       or a <literal>0</literal> for no).</para>
1532
1533     <para>If you want to set automatically some variables each time
1534       the machine boots, add them to the
1535       <filename>/etc/sysctl.conf</filename> file.  For more information
1536       see the &man.sysctl.conf.5; manual page and the
1537       <xref linkend="configtuning-sysctlconf">.</para>
1538
1539   <sect2 id="sysctl-readonly">
1540     <sect2info>
1541       <authorgroup>
1542         <author>
1543          <firstname>Tom</firstname>
1544          <surname>Rhodes</surname>
1545          <contrib>Contributed by </contrib>
1546          <!-- 31 January 2003 -->
1547         </author>
1548       </authorgroup>
1549     </sect2info>
1550     <title>&man.sysctl.8; Read-only</title>
1551
1552     <para>In some cases it may be desirable to modify read-only &man.sysctl.8;
1553       values.  While this is not recommended, it is also sometimes unavoidable.</para>
1554
1555     <para>For instance on some laptop models the &man.cardbus.4; device will
1556       not probe memory ranges, and fail with errors which look similar to:</para>
1557
1558     <screen>cbb0: Could not map register memory
1559 device_probe_and_attach: cbb0 attach returned 12</screen>
1560
1561     <para>Cases like the one above usually require the modification of some
1562       default &man.sysctl.8; settings which are set read only.  To overcome
1563       these situations a user can put &man.sysctl.8; <quote>OIDs</quote>
1564       in their local <filename>/boot/loader.conf</filename>.  Default
1565       settings are located in the <filename>/boot/defaults/loader.conf</filename>
1566       file.</para>
1567
1568     <para>Fixing the problem mentioned above would require a user to set
1569       <option>hw.pci.allow_unsupported_io_range=1</option> in the aforementioned
1570       file.  Now &man.cardbus.4; will work properly.</para>
1571
1572     </sect2>
1573   </sect1>
1574
1575   <sect1 id="configtuning-disk">
1576     <title>Tuning Disks</title>
1577
1578     <sect2>
1579       <title>Sysctl Variables</title>
1580
1581       <sect3>
1582         <title><varname>vfs.vmiodirenable</varname></title>
1583
1584         <indexterm>
1585           <primary><varname>vfs.vmiodirenable</varname></primary>
1586         </indexterm>
1587
1588         <para>The <varname>vfs.vmiodirenable</varname> sysctl variable
1589           may be set to either 0 (off) or 1 (on); it is 1 by default.
1590           This variable controls how directories are cached by the
1591           system.  Most directories are small, using just a single
1592           fragment (typically 1&nbsp;K) in the file system and less
1593           (typically 512&nbsp;bytes) in the buffer cache.
1594           With this variable turned off (to 0), the buffer
1595           cache will only cache a fixed number of directories even if
1596           ou have a huge amount of memory.  When turned on (to 1), this sysctl
1597           allows the buffer cache to use the VM Page Cache to cache the
1598           directories, making all the memory available for caching
1599           directories.  However,
1600           the minimum in-core memory used to cache a directory is the
1601           physical page size (typically 4&nbsp;K) rather than 512&nbsp;
1602           bytes.  We recommend keeping this option on if you are running
1603           any services which manipulate large numbers of files.  Such
1604           services can include web caches, large mail systems, and news
1605           systems.  Keeping this option on will generally not reduce
1606           performance even with the wasted memory but you should
1607           experiment to find out.</para>
1608       </sect3>
1609
1610      <sect3>
1611         <title><varname>vfs.write_behind</varname></title>
1612
1613         <indexterm>
1614           <primary><varname>vfs.write_behind</varname></primary>
1615         </indexterm>
1616
1617         <para>The <varname>vfs.write_behind</varname> sysctl variable
1618           defaults to <literal>1</literal> (on).  This tells the file system
1619           to issue media writes as full clusters are collected, which
1620           typically occurs when writing large sequential files.  The idea
1621           is to avoid saturating the buffer cache with dirty buffers when
1622           it would not benefit I/O performance.  However, this may stall
1623           processes and under certain circumstances you may wish to turn it
1624           off.</para>
1625        </sect3>
1626
1627        <sect3>
1628         <title><varname>vfs.hirunningspace</varname></title>
1629
1630         <indexterm>
1631           <primary><varname>vfs.hirunningspace</varname></primary>
1632         </indexterm>
1633
1634         <para>The <varname>vfs.hirunningspace</varname> sysctl variable
1635           determines how much outstanding write I/O may be queued to disk
1636           controllers system-wide at any given instance.  The default is
1637           usually sufficient but on machines with lots of disks you may
1638           want to bump it up to four or five <emphasis>megabytes</emphasis>.
1639           Note that setting too high a value (exceeding the buffer cache's
1640           write threshold) can lead to extremely bad clustering
1641           performance.  Do not set this value arbitrarily high!  Higher
1642           write values may add latency to reads occurring at the same time.
1643         </para>
1644
1645         <para>There are various other buffer-cache and VM page cache
1646           related sysctls.  We do not recommend modifying these values.  
1647           The VM system does an extremely good job of
1648           automatically tuning itself.</para>
1649        </sect3>
1650
1651        <sect3>
1652         <title><varname>vm.swap_idle_enabled</varname></title>
1653
1654         <indexterm>
1655           <primary><varname>vm.swap_idle_enabled</varname></primary>
1656         </indexterm>
1657
1658         <para>The <varname>vm.swap_idle_enabled</varname> sysctl variable
1659           is useful in large multi-user systems where you have lots of
1660           users entering and leaving the system and lots of idle processes.
1661           Such systems tend to generate a great deal of continuous pressure
1662           on free memory reserves.  Turning this feature on and tweaking
1663           the swapout hysteresis (in idle seconds) via
1664           <varname>vm.swap_idle_threshold1</varname> and
1665           <varname>vm.swap_idle_threshold2</varname> allows you to depress
1666           the priority of memory pages associated with idle processes more
1667           quickly then the normal pageout algorithm.  This gives a helping
1668           hand to the pageout daemon.  Do not turn this option on unless
1669           you need it, because the tradeoff you are making is essentially
1670           pre-page memory sooner rather than later; thus eating more swap
1671           and disk bandwidth.  In a small system this option will have a
1672           determinable effect but in a large system that is already doing
1673           moderate paging this option allows the VM system to stage whole
1674           processes into and out of memory easily.</para>
1675        </sect3>
1676
1677       <sect3>
1678         <title><varname>hw.ata.wc</varname></title>
1679
1680         <indexterm>
1681           <primary><varname>hw.ata.wc</varname></primary>
1682         </indexterm>
1683
1684         <para>IDE drives lie about when a write completes.  With IDE write
1685           caching turned on, IDE hard drives not only write data
1686           to disk out of order, but will sometimes delay writing some
1687           blocks indefinitely when under heavy disk loads.  A crash or
1688           power failure may cause serious file system corruption. Turning 
1689           off write caching will remove the danger of this data loss, but 
1690           will also cause disk operations to proceed 
1691           <emphasis>very slowly.</emphasis>  Change this only if prepared 
1692           to suffer with the disk slowdown.</para>
1693           
1694         <para>Changing this variable must be done from the
1695           boot loader at boot time.  Attempting to do it after the
1696           kernel boots will have no effect.</para>
1697
1698         <para>For more information, please see &man.ata.4; manual page.</para>
1699       </sect3>
1700
1701     </sect2>
1702
1703     <sect2 id="soft-updates">
1704       <title>Soft Updates</title>
1705
1706       <indexterm><primary>Soft Updates</primary></indexterm>
1707       <indexterm><primary>tunefs</primary></indexterm>
1708
1709       <para>The &man.tunefs.8; program can be used to fine-tune a
1710         file system.  This program has many different options, but for
1711         now we are only concerned with toggling Soft Updates on and
1712         off, which is done by:</para>
1713
1714       <screen>&prompt.root; <userinput>tunefs -n enable /filesystem</userinput>
1715 &prompt.root; <userinput>tunefs -n disable /filesystem</userinput></screen>
1716
1717       <para>A filesystem cannot be modified with &man.tunefs.8; while
1718         it is mounted.  A good time to enable Soft Updates is before any
1719         partitions have been mounted, in single-user mode.</para>
1720
1721       <note><para>It is possible to enable Soft Updates
1722         at filesystem creation time, through use of the <literal>-U</literal>
1723         option to &man.newfs.8;.</para></note>
1724
1725       <para>Soft Updates drastically improves meta-data performance, mainly
1726         file creation and deletion, through the use of a memory cache.  We
1727         recommend to use Soft Updates on all of your file systems.  There
1728         are two downsides to Soft Updates that you should be aware of:  First,
1729         Soft Updates guarantees filesystem consistency in the case of a crash
1730         but could very easily be several seconds (even a minute!) behind
1731         updating the physical disk.  If your system crashes you may lose more
1732         work than otherwise.  Secondly, Soft Updates delays the freeing of
1733         filesystem blocks.  If you have a filesystem (such as the root
1734         filesystem) which is almost full, performing a major update, such as
1735         <command>make installworld</command>, can cause the filesystem to run
1736         out of space and the update to fail.</para>
1737
1738       <sect3>
1739         <title>More Details about Soft Updates</title>
1740
1741         <indexterm>
1742           <primary>Soft Updates</primary>
1743           <secondary>details</secondary>
1744         </indexterm>
1745
1746         <para>There are two traditional approaches to writing a file
1747           systems meta-data back to disk.  (Meta-data updates are
1748           updates to non-content data like inodes or
1749           directories.)</para>
1750
1751         <para>Historically, the default behavior was to write out
1752           meta-data updates synchronously.  If a directory had been
1753           changed, the system waited until the change was actually
1754           written to disk.  The file data buffers (file contents) were
1755           passed through the buffer cache and backed up
1756           to disk later on asynchronously.  The advantage of this
1757           implementation is that it operates safely.  If there is
1758           a failure during an update, the meta-data are always in a
1759           consistent state.  A file is either created completely
1760           or not at all.  If the data blocks of a file did not find
1761           their way out of the buffer cache onto the disk by the time
1762           of the crash, &man.fsck.8; is able to recognize this and
1763           repair the filesystem by setting the file length to
1764           0.  Additionally, the implementation is clear and simple.
1765           The disadvantage is that meta-data changes are slow.  An
1766           <command>rm -r</command>, for instance, touches all the files
1767           in a directory sequentially, but each directory
1768           change (deletion of a file) will be written synchronously
1769           to the disk.  This includes updates to the directory itself,
1770           to the inode table, and possibly to indirect blocks
1771           allocated by the file.  Similar considerations apply for
1772           unrolling large hierarchies (<command>tar -x</command>).</para>
1773
1774         <para>The second case is asynchronous meta-data updates.  This
1775           is the default for Linux/ext2fs and
1776           <command>mount -o async</command> for *BSD ufs.  All
1777           meta-data updates are simply being passed through the buffer
1778           cache too, that is, they will be intermixed with the updates
1779           of the file content data.  The advantage of this
1780           implementation is there is no need to wait until each
1781           meta-data update has been written to disk, so all operations
1782           which cause huge amounts of meta-data updates work much
1783           faster than in the synchronous case.  Also, the
1784           implementation is still clear and simple, so there is a low
1785           risk for bugs creeping into the code.  The disadvantage is
1786           that there is no guarantee at all for a consistent state of
1787           the filesystem.  If there is a failure during an operation
1788           that updated large amounts of meta-data (like a power
1789           failure, or someone pressing the reset button),
1790           the filesystem
1791           will be left in an unpredictable state.  There is no opportunity
1792           to examine the state of the filesystem when the system
1793           comes up again; the data blocks of a file could already have
1794           been written to the disk while the updates of the inode
1795           table or the associated directory were not.  It is actually
1796           impossible to implement a <command>fsck</command> which is
1797           able to clean up the resulting chaos (because the necessary
1798           information is not available on the disk).  If the
1799           filesystem has been damaged beyond repair, the only choice
1800           is to use &man.newfs.8; on it and restore it from backup.
1801           </para>
1802
1803         <para>The usual solution for this problem was to implement
1804           <emphasis>dirty region logging</emphasis>, which is also
1805           referred to as <emphasis>journaling</emphasis>, although that
1806           term is not used consistently and is occasionally applied
1807           to other forms of transaction logging as well.  Meta-data
1808           updates are still written synchronously, but only into a
1809           small region of the disk.  Later on they will be moved
1810           to their proper location.  Because the logging
1811           area is a small, contiguous region on the disk, there
1812           are no long distances for the disk heads to move, even
1813           during heavy operations, so these operations are quicker
1814           than synchronous updates.
1815           Additionally the complexity of the implementation is fairly
1816           limited, so the risk of bugs being present is low.  A disadvantage
1817           is that all meta-data are written twice (once into the
1818           logging region and once to the proper location) so for
1819           normal work, a performance <quote>pessimization</quote>
1820           might result.  On the other hand, in case of a crash, all
1821           pending meta-data operations can be quickly either rolled-back
1822           or completed from the logging area after the system comes
1823           up again, resulting in a fast filesystem startup.</para>
1824
1825         <para>Kirk McKusick, the developer of Berkeley FFS,
1826            solved this problem with Soft Updates: all pending
1827            meta-data updates are kept in memory and written out to disk
1828            in a sorted sequence (<quote>ordered meta-data
1829            updates</quote>).  This has the effect that, in case of
1830            heavy meta-data operations, later updates to an item
1831            <quote>catch</quote> the earlier ones if the earlier ones are still in
1832            memory and have not already been written to disk.  So all
1833            operations on, say, a directory are generally performed in
1834            memory before the update is written to disk (the data
1835            blocks are sorted according to their position so
1836            that they will not be on the disk ahead of their meta-data).
1837            If the system crashes, this causes an implicit <quote>log
1838            rewind</quote>: all operations which did not find their way
1839            to the disk appear as if they had never happened.  A
1840            consistent filesystem state is maintained that appears to
1841            be the one of 30 to 60 seconds earlier.  The
1842            algorithm used guarantees that all resources in use
1843            are marked as such in their appropriate bitmaps: blocks and inodes.
1844            After a crash, the only resource allocation error
1845            that occurs is that resources are
1846            marked as <quote>used</quote> which are actually <quote>free</quote>.
1847            &man.fsck.8; recognizes this situation,
1848            and frees the resources that are no longer used.  It is safe to
1849            ignore the dirty state of the filesystem after a crash by
1850            forcibly mounting it with <command>mount -f</command>.  In
1851            order to free resources that may be unused, &man.fsck.8;
1852            needs to be run at a later time.</para>
1853
1854          <para>The advantage is that meta-data operations are nearly as
1855            fast as asynchronous updates (i.e. faster than with
1856            <emphasis>logging</emphasis>, which has to write the
1857            meta-data twice).  The disadvantages are the complexity of
1858            the code (implying a higher risk for bugs in an area that
1859            is highly sensitive regarding loss of user data), and a
1860            higher memory consumption.  Additionally there are some
1861            idiosyncrasies one has to get used to.
1862            After a crash, the state of the filesystem appears to be
1863            somewhat <quote>older</quote>.  In situations where
1864            the standard synchronous approach would have caused some
1865            zero-length files to remain after the
1866            <command>fsck</command>, these files do not exist at all
1867            with a Soft Updates filesystem because neither the meta-data
1868            nor the file contents have ever been written to disk.
1869            Disk space is not released until the updates have been
1870            written to disk, which may take place some time after
1871            running <command>rm</command>.  This may cause problems
1872            when installing large amounts of data on a filesystem
1873            that does not have enough free space to hold all the files
1874            twice.</para>
1875       </sect3>
1876     </sect2>
1877   </sect1>
1878
1879   <sect1 id="configtuning-kernel-limits">
1880     <title>Tuning Kernel Limits</title>
1881
1882     <indexterm>
1883       <primary>tuning</primary>
1884       <secondary>kernel limits</secondary>
1885     </indexterm>
1886
1887     <sect2 id="file-process-limits">
1888       <title>File/Process Limits</title>
1889
1890       <sect3 id="kern-maxfiles">
1891         <title><varname>kern.maxfiles</varname></title>
1892
1893         <indexterm>
1894           <primary><varname>kern.maxfiles</varname></primary>
1895         </indexterm>
1896
1897         <para><varname>kern.maxfiles</varname> can be raised or
1898           lowered based upon your system requirements.  This variable
1899           indicates the maximum number of file descriptors on your
1900           system.  When the file descriptor table is full,
1901           <errorname>file: table is full</errorname> will show up repeatedly
1902           in the system message buffer, which can be viewed with the
1903           <command>dmesg</command> command.</para>
1904
1905         <para>Each open file, socket, or fifo uses one file
1906           descriptor.  A large-scale production server may easily
1907           require many thousands of file descriptors, depending on the
1908           kind and number of services running concurrently.</para>
1909
1910         <para><varname>kern.maxfile</varname>'s default value is
1911           dictated by the <option>MAXUSERS</option> option in your
1912           kernel configuration file.  <varname>kern.maxfiles</varname> grows
1913           proportionally to the value of <option>MAXUSERS</option>.  When
1914           compiling a custom kernel, it is a good idea to set this kernel
1915           configuration option according to the uses of your system.  From
1916           this number, the kernel is given most of its pre-defined limits.
1917           Even though a production machine may not actually have 256 users
1918           connected at once, the resources needed may be similar to a
1919           high-scale web server.</para>
1920
1921         <note><para>Setting <option>MAXUSERS</option> to
1922           <literal>0</literal> in your kernel configuration file will choose
1923           a reasonable default value based on the amount of RAM present in
1924           your system.  It is set to 0 in the default GENERIC kernel.</para></note>
1925
1926       </sect3>
1927
1928       <sect3>
1929         <title><varname>kern.ipc.somaxconn</varname></title>
1930
1931         <indexterm>
1932           <primary><varname>kern.ipc.somaxconn</varname></primary>
1933         </indexterm>
1934
1935         <para>The <varname>kern.ipc.somaxconn</varname> sysctl variable
1936           limits the size of the listen queue for accepting new TCP
1937           connections.  The default value of <literal>128</literal> is
1938           typically too low for robust handling of new connections in a
1939           heavily loaded web server environment.  For such environments, it
1940           is recommended to increase this value to <literal>1024</literal> or
1941           higher.  The service daemon may itself limit the listen queue size
1942           (e.g. &man.sendmail.8;, or <application>Apache</application>) but
1943           will often have a directive in its configuration file to adjust
1944           the queue size.  Large listen queues also do a better job of
1945           avoiding Denial of Service (<abbrev>DoS</abbrev>) attacks.</para>
1946       </sect3>
1947
1948     </sect2>
1949     <sect2>
1950       <title>Network Limits</title>
1951
1952       <para>The <literal>NMBCLUSTERS</literal> kernel configuration
1953         option dictates the amount of network Mbufs available to the
1954         system.  A heavily-trafficked server with a low number of Mbufs
1955         will hinder &os;'s ability.  Each cluster represents
1956         approximately 2&nbsp;K of memory, so a value of 1024 represents 2
1957         megabytes of kernel memory reserved for network buffers.  A
1958         simple calculation can be done to figure out how many are
1959         needed.  If you have a web server which maxes out at 1000
1960         simultaneous connections, and each connection eats a 16&nbsp;K receive
1961         and 16&nbsp;K send buffer, you need approximately 32&nbsp;MB worth of
1962         network buffers to cover the web server.  A good rule of thumb is
1963         to multiply by 2, so 2x32&nbsp;MB&nbsp;/&nbsp;2&nbsp;KB&nbsp;=
1964         64&nbsp;MB&nbsp;/&nbsp;2&nbsp;kB&nbsp;= 32768.  We recommend
1965         values between 4096 and 32768 for machines with greater amounts
1966         of memory.  Under no circumstances should you specify an
1967         arbitrarily high value for this parameter as it could lead to a
1968         boot time crash.  The <option>-m</option> option to
1969         &man.netstat.1; may be used to observe network cluster
1970         use.  <varname>kern.ipc.nmbclusters</varname> loader tunable should
1971         be used to tune this at boot time.</para>
1972
1973       <para>For busy servers that make extensive use of the
1974         &man.sendfile.2; system call, it may be necessary to increase
1975         the number of &man.sendfile.2; buffers via the
1976         <literal>NSFBUFS</literal> kernel configuration option or by
1977         setting its value in <filename>/boot/loader.conf</filename>
1978         (see &man.loader.8; for details).  A common indicator that
1979         this parameter needs to be adjusted is when processes are seen
1980         in the <literal>sfbufa</literal> state.  The sysctl
1981         variable <varname>kern.ipc.nsfbufs</varname> is a read-only
1982         glimpse at the kernel configured variable.  This parameter
1983         nominally scales with <varname>kern.maxusers</varname>,
1984         however it may be necessary to tune accordingly.</para>
1985
1986       <important>
1987         <para>Even though a socket has been marked as non-blocking,
1988           calling &man.sendfile.2; on the non-blocking socket may
1989           result in the &man.sendfile.2; call blocking until enough
1990           <literal>struct sf_buf</literal>'s are made
1991           available.</para>
1992       </important>
1993
1994       <sect3>
1995         <title><varname>net.inet.ip.portrange.*</varname></title>
1996
1997         <indexterm>
1998           <primary>net.inet.ip.portrange.*</primary>
1999         </indexterm>
2000
2001         <para>The <varname>net.inet.ip.portrange.*</varname> sysctl
2002           variables control the port number ranges automatically bound to TCP
2003           and UDP sockets.  There are three ranges: a low range, a default
2004           range, and a high range.  Most network programs use the default
2005           range which is controlled by the
2006           <varname>net.inet.ip.portrange.first</varname> and
2007           <varname>net.inet.ip.portrange.last</varname>, which default to
2008           1024 and 5000, respectively.  Bound port ranges are used  for
2009           outgoing connections, and it is possible to run the system out of
2010           ports under certain circumstances.  This most commonly occurs
2011           when you are running a heavily loaded web proxy.  The port range
2012           is not an issue when running servers which handle mainly incoming
2013           connections, such as a normal web server, or has a limited number
2014           of outgoing connections, such as a mail relay.  For situations
2015           where you may run yourself out of ports, it is recommended to
2016           increase <varname>net.inet.ip.portrange.last</varname> modestly.
2017           A value of <literal>10000</literal>, <literal>20000</literal> or
2018           <literal>30000</literal> may be reasonable.  You should also
2019           consider firewall effects when changing the port range.  Some
2020           firewalls may block large ranges of ports (usually low-numbered
2021           ports) and expect systems to use higher ranges of ports for
2022           outgoing connections &mdash; for this reason it is recommended that
2023           <varname>net.inet.ip.portrange.first</varname> be lowered.</para>
2024       </sect3>
2025
2026       <sect3>
2027         <title>TCP Bandwidth Delay Product</title>
2028
2029         <indexterm>
2030           <primary>TCP Bandwidth Delay Product Limiting</primary>
2031           <secondary><varname>net.inet.tcp.inflight_enable</varname></secondary>
2032         </indexterm>
2033
2034         <para>The TCP Bandwidth Delay Product Limiting is similar to
2035           TCP/Vegas in NetBSD.
2036
2037           <indexterm><primary>&netbsd;</primary></indexterm>
2038           
2039           It can be
2040           enabled by setting <varname>net.inet.tcp.inflight_enable</varname>
2041           sysctl variable to <literal>1</literal>.  The system will attempt
2042           to calculate the bandwidth delay product for each connection and
2043           limit the amount of data queued to the network to just the amount
2044           required to maintain optimum throughput.</para>
2045
2046         <para>This feature is useful if you are serving data over modems,
2047           Gigabit Ethernet, or even high speed WAN links (or any other link
2048           with a high bandwidth delay product), especially if you are also
2049           using window scaling or have configured a large send window.  If
2050           you enable this option, you should also be sure to set
2051           <varname>net.inet.tcp.inflight_debug</varname> to
2052           <literal>0</literal> (disable debugging), and for production use
2053           setting <varname>net.inet.tcp.inflight_min</varname> to at least
2054           <literal>6144</literal> may be beneficial.  However, note that
2055           setting high minimums may effectively disable bandwidth limiting
2056           depending on the link.  The limiting feature reduces the amount of
2057           data built up in intermediate route and switch packet queues as
2058           well as reduces the amount of data built up in the local host's
2059           interface queue.  With fewer packets queued up, interactive
2060           connections, especially over slow modems, will also be able to
2061           operate with lower <emphasis>Round Trip Times</emphasis>.  However,
2062           note that this feature only effects data transmission (uploading
2063           / server side).  It has no effect on data reception (downloading).
2064         </para>
2065
2066         <para>Adjusting <varname>net.inet.tcp.inflight_stab</varname> is
2067           <emphasis>not</emphasis> recommended.  This parameter defaults to
2068           20, representing 2 maximal packets added to the bandwidth delay
2069           product window calculation.  The additional window is required to
2070           stabilize the algorithm and improve responsiveness to changing
2071           conditions, but it can also result in higher ping times over slow
2072           links (though still much lower than you would get without the
2073           inflight algorithm).  In such cases, you may wish to try reducing
2074           this parameter to 15, 10, or 5; and may also have to reduce
2075           <varname>net.inet.tcp.inflight_min</varname> (for example, to
2076           3500) to get the desired effect.  Reducing these parameters
2077           should be done as a last resort only.</para>
2078       </sect3>
2079     </sect2>
2080   </sect1>
2081
2082   <sect1 id="adding-swap-space">
2083     <title>Adding Swap Space</title>
2084
2085     <para>No matter how well you plan, sometimes a system does not run
2086       as you expect.  If you find you need more swap space, it is
2087       simple enough to add.  You have three ways to increase swap
2088       space: adding a new hard drive, enabling swap over NFS, and
2089       creating a swap file on an existing partition.</para>
2090
2091     <sect2 id="new-drive-swap">
2092       <title>Swap on a New Hard Drive</title>
2093
2094       <para>The best way to add swap, of course, is to use this as an
2095         excuse to add another hard drive.  You can always use another
2096         hard drive, after all.  If you can do this, go reread the
2097         discussion about swap space in <xref linkend="configtuning-initial">
2098         for some suggestions on how to best arrange your swap.</para>
2099     </sect2>
2100
2101     <sect2 id="nfs-swap">
2102       <title>Swapping over NFS</title>
2103
2104       <para>Swapping over NFS is only recommended if you do not have a
2105         local hard disk to swap to.  Even though &os;  has an excellent 
2106         NFS implementation, NFS swapping will be limited
2107         by the available network bandwidth and puts an additional
2108         burden on the NFS server.</para>
2109     </sect2>
2110
2111     <sect2 id="create-swapfile">
2112       <title>Swapfiles</title>
2113
2114       <para>You can create a file of a specified size to use as a swap
2115         file.  In our example here we will use a 64MB file called
2116         <filename>/usr/swap0</filename>.  You can use any name you
2117         want, of course.</para>
2118
2119       <example>
2120         <title>Creating a Swapfile</title>
2121
2122       <orderedlist>
2123         <listitem>
2124           <para>Be certain that your kernel configuration includes
2125             the vnode driver.  It is <emphasis>not</emphasis> in recent versions of
2126             <filename>GENERIC</filename>.</para>
2127
2128           <programlisting>pseudo-device   vn 1   #Vnode driver (turns a file into a device)</programlisting>
2129         </listitem>
2130
2131         <listitem>
2132           <para>Create a vn-device:</para>
2133           <screen>&prompt.root; <userinput>cd /dev</userinput>
2134 &prompt.root; <userinput>sh MAKEDEV vn0</userinput></screen>
2135         </listitem>
2136
2137         <listitem>
2138           <para>Create a swapfile (<filename>/usr/swap0</filename>):</para>
2139
2140           <screen>&prompt.root; <userinput>dd if=/dev/zero of=/usr/swap0 bs=1024k count=64</userinput></screen>
2141         </listitem>
2142
2143         <listitem>
2144           <para>Set proper permissions on (<filename>/usr/swap0</filename>):</para>
2145
2146           <screen>&prompt.root; <userinput>chmod 0600 /usr/swap0</userinput></screen>
2147         </listitem>
2148
2149         <listitem>
2150           <para>Enable the swap file in <filename>/etc/rc.conf</filename>:</para>
2151
2152           <programlisting>swapfile="/usr/swap0"   # Set to name of swapfile if aux swapfile desired.</programlisting>
2153         </listitem>
2154
2155         <listitem>
2156
2157           <para>Reboot the machine or to enable the swap file immediately,
2158             type:</para>
2159
2160           <screen>&prompt.root; <userinput>vnconfig -e /dev/vn0b /usr/swap0 swap</userinput></screen>
2161         </listitem>
2162       </orderedlist>
2163
2164       </example>
2165     </sect2>
2166   </sect1>
2167
2168   <sect1 id="acpi-overview">
2169     <sect1info>
2170       <authorgroup>
2171         <author>
2172           <firstname>Hiten</firstname>
2173           <surname>Pandya</surname>
2174           <contrib>Written by </contrib>
2175         </author>
2176         <author>
2177           <firstname>Tom</firstname>
2178           <surname>Rhodes</surname>
2179         </author>
2180       </authorgroup>
2181     </sect1info>
2182
2183     <title>Power and Resource Management</title>
2184
2185     <para>It is very important to utilize hardware resources in an
2186       efficient manner.  Before <acronym>ACPI</acronym> was introduced,
2187       it was very difficult and inflexible for operating systems to manage
2188       the power usage and thermal properties of a system.  The hardware was
2189       controlled by some sort of <acronym>BIOS</acronym> embedded
2190       interface, such as <emphasis>Plug and Play BIOS (PNPBIOS)</emphasis>, or
2191       <emphasis>Advanced Power Management (APM)</emphasis> and so on.
2192       Power and Resource Management is one of the key components of a modern
2193       operating system.  For example, you may want an operating system to
2194       monitor system limits (and possibly alert you) in case your system
2195       temperature increased unexpectedly.</para>
2196
2197     <para>In this section, we will provide
2198       comprehensive information about <acronym>ACPI</acronym>.  References
2199       will be provided for further reading at the end.  Please be aware
2200       that <acronym>ACPI</acronym> is available on &os; systems as a 
2201       default kernel module.  </para>
2202
2203     <sect2 id="acpi-intro">
2204       <title>What Is ACPI?</title>
2205
2206       <para>Advanced Configuration and Power Interface
2207         (<acronym>ACPI</acronym>) is a standard written by
2208         an alliance of vendors to provide a standard interface for
2209         hardware resources and power management (hence the name).
2210         It is a key element in <emphasis>Operating System-directed
2211         configuration and Power Management</emphasis>, i.e.: it provides
2212         more control and flexibility to the operating system
2213         (<acronym>OS</acronym>).
2214         Modern systems <quote>stretched</quote> the limits of the
2215         current Plug and Play interfaces (such as APM), prior to the introduction of
2216         <acronym>ACPI</acronym>.  <acronym>ACPI</acronym> is the direct
2217         successor to <acronym>APM</acronym>
2218         (Advanced Power Management).</para>
2219     </sect2>
2220
2221     <sect2 id="acpi-old-spec">
2222       <title>Shortcomings of Advanced Power Management (APM)</title>
2223
2224       <para>The <emphasis>Advanced Power Management (APM)</emphasis>
2225       facility control's the power usage of a system based on its
2226       activity.  The APM BIOS is supplied by the (system) vendor and
2227       it is specific to the hardware platform.  An APM driver in the
2228       OS mediates access to the <emphasis>APM Software Interface</emphasis>,
2229       which allows management of power levels.</para>
2230
2231       <para>There are four major problems in APM.  Firstly, power
2232       management is done by the (vendor-specific) BIOS, and the OS
2233       does not have any knowledge of it.  One example of this, is when
2234       the user sets idle-time values for a hard drive in the APM BIOS,
2235       that when exceeded, it (BIOS) would spin down the hard drive,
2236       without the consent of the OS.  Secondly, the APM logic is
2237       embedded in the BIOS, and it operates outside the scope of the
2238       OS.  This means users can only fix problems in their APM BIOS by
2239       flashing a new one into the ROM; which, is a very dangerous
2240       procedure, and if it fails, it could leave the system in an
2241       unrecoverable state. Thirdly, APM is a vendor-specific
2242       technology, which, means that there is a lot or parity
2243       (duplication of efforts) and bugs found in one vendor's BIOS,
2244       may not be solved in others.  Last but not the least, the APM
2245       BIOS did not have enough room to implement a sophisticated power
2246       policy, or one that can adapt very well to the purpose of the
2247       machine.</para>
2248
2249       <para><emphasis>Plug and Play BIOS (PNPBIOS)</emphasis> was
2250       unreliable in many situations.  PNPBIOS is 16-bit technology,
2251       so the OS has to use 16-bit emulation in order to
2252       <quote>interface</quote> with PNPBIOS methods.</para>
2253
2254       <para>The &os; <acronym>APM</acronym> driver is documented in
2255       the &man.apm.4; manual page.</para>
2256     </sect2>
2257
2258     <sect2 id="acpi-config">
2259       <title>Configuring <acronym>ACPI</acronym></title>
2260
2261       <para>The <filename>acpi.ko</filename> driver is loaded by default
2262         at start up by the &man.loader.8; and should <emphasis>not</emphasis>
2263         be compiled into the kernel.  The reasoning behind this is that modules
2264         are easier to work with, say if switching to another <filename>acpi.ko</filename>
2265         without doing a kernel rebuild.  This has the advantage of making testing easier.
2266         Another reason is that starting <acronym>ACPI</acronym> after a system has been
2267         brought up is not too useful, and in some cases can be fatal.  In doubt, just
2268         disable <acronym>ACPI</acronym> all together. This driver should not and can not
2269         be unloaded because the system bus uses it for various hardware interactions.
2270         <acronym>ACPI</acronym> can be disabled with the &man.acpiconf.8; utility.
2271         In fact most of the interaction with <acronym>ACPI</acronym> can be done via
2272         &man.acpiconf.8;.  Basically this means, if anything about <acronym>ACPI</acronym>
2273         is in the &man.dmesg.8; output, then most likely it is already running.</para>
2274
2275       <note><para><acronym>ACPI</acronym> and <acronym>APM</acronym> cannot coexist and
2276         should be used separately.  The last one to load will terminate if the driver
2277         notices the other running.</para></note>
2278
2279       <para>In the simplest form, <acronym>ACPI</acronym> can be used to put the
2280         system into a sleep mode with &man.acpiconf.8;, the <option>-s</option>
2281         flag, and a <literal>1-5</literal> option.  Most users will only need
2282         <literal>1</literal>.  Option <literal>5</literal> will do a soft-off
2283         which is the same action as:</para>
2284
2285       <screen>&prompt.root; <userinput>halt -p</userinput></screen>
2286
2287       <para>The other options are available.  Check out the &man.acpiconf.8;
2288         manual page for more information.</para>
2289     </sect2>
2290   </sect1>
2291
2292   <sect1 id="ACPI-debug">
2293     <sect1info>
2294       <authorgroup>
2295         <author>
2296           <firstname>Nate</firstname>
2297           <surname>Lawson</surname>
2298           <contrib>Written by </contrib>
2299         </author>
2300       </authorgroup>
2301       <authorgroup>
2302         <author>
2303           <firstname>Peter</firstname>
2304           <surname>Schultz</surname>
2305           <contrib>With contributions from </contrib>
2306         </author>
2307         <author>
2308           <firstname>Tom</firstname>
2309           <surname>Rhodes</surname>
2310         </author>
2311       </authorgroup>
2312     </sect1info>
2313
2314     <title>Using and Debugging &os; <acronym>ACPI</acronym></title>
2315
2316     <para><acronym>ACPI</acronym> is a fundamentally new way of
2317       discovering devices, managing power usage, and providing
2318       standardized access to various hardware previously managed
2319       by the <acronym>BIOS</acronym>.  Progress is being made toward
2320       <acronym>ACPI</acronym> working on all systems, but bugs in some
2321       motherboards' <firstterm><acronym>ACPI</acronym> Machine
2322       Language</firstterm> (<acronym>AML</acronym>) bytecode,
2323       incompleteness in &os;'s kernel subsystems, and bugs in the Intel
2324       <acronym>ACPI-CA</acronym> interpreter continue to appear.</para>
2325
2326     <para>This document is intended to help you assist the &os;
2327       <acronym>ACPI</acronym> maintainers in identifying the root cause
2328       of problems you observe and debugging and developing a solution.
2329       Thanks for reading this and we hope we can solve your system's
2330       problems.</para>
2331
2332     <sect2 id="ACPI-submitdebug">
2333       <title>Submitting Debugging Information</title>
2334
2335       <note>
2336         <para>Before submitting a problem, be sure you are running the latest
2337           <acronym>BIOS</acronym> version and, if available, embedded
2338           controller firmware version.</para>
2339       </note>
2340
2341       <para>For those of you that want to submit a problem right away,
2342         please send the following information to
2343         &a.bugs.name;</para>
2344
2345       <itemizedlist>
2346         <listitem>
2347           <para>Description of the buggy behavior, including system type
2348             and model and anything that causes the bug to appear.  Also,
2349             please note as accurately as possible when the bug began
2350             occurring if it is new for you.</para>
2351         </listitem>
2352
2353         <listitem>
2354           <para>The dmesg output after <quote>boot
2355             <option>-v</option></quote>, including any error messages
2356             generated by you exercising the bug.</para>
2357         </listitem>
2358
2359         <listitem>
2360           <para>dmesg output from <quote>boot
2361             <option>-v</option></quote> with <acronym>ACPI</acronym>
2362             disabled, if disabling it helps fix the problem.</para>
2363         </listitem>
2364
2365         <listitem>
2366           <para>Output from <quote>sysctl hw.acpi</quote>.  This is also
2367             a good way of figuring out what features your system
2368             offers.</para>
2369         </listitem>
2370
2371         <listitem>
2372           <para><acronym>URL</acronym> where your
2373             <firstterm><acronym>ACPI</acronym> Source Language</firstterm>
2374             (<acronym>ASL</acronym>)
2375             can be found.  Do <emphasis>not</emphasis> send the
2376             <acronym>ASL</acronym> directly to the list as it can be
2377             very large.  Generate a copy of your <acronym>ASL</acronym>
2378             by running this command:</para>
2379
2380           <screen>&prompt.root; <userinput>acpidump -t -d &gt; <replaceable>name</replaceable>-<replaceable>system</replaceable>.asl</userinput></screen>
2381
2382           <para>(Substitute your login name for
2383             <replaceable>name</replaceable> and manufacturer/model for
2384             <replaceable>system</replaceable>.  Example:
2385             <filename>njl-FooCo6000.asl</filename>)</para>
2386         </listitem>
2387       </itemizedlist>
2388
2389     </sect2>
2390
2391     <sect2 id="ACPI-background">
2392       <title>Background</title>
2393
2394       <para><acronym>ACPI</acronym> is present in all modern computers
2395         that conform to the ia32 (x86), ia64 (Itanium), and amd64 (AMD)
2396         architectures.  The full standard has many features including
2397         <acronym>CPU</acronym> performance management, power planes
2398         control, thermal zones, various battery systems, embedded
2399         controllers, and bus enumeration.  Most systems implement less
2400         than the full standard.  For instance, a desktop system usually
2401         only implements the bus enumeration parts while a laptop might
2402         have cooling and battery management support as well.  Laptops
2403         also have suspend and resume, with their own associated
2404         complexity.</para>
2405
2406       <para>An <acronym>ACPI</acronym>-compliant system has various
2407         components.  The <acronym>BIOS</acronym> and chipset vendors
2408         provide various fixed tables (e.g., <acronym>FADT</acronym>)
2409         in memory that specify things like the <acronym>APIC</acronym>
2410         map (used for <acronym>SMP</acronym>), config registers, and
2411         simple configuration values.  Additionally, a table of bytecode
2412         (the <firstterm>Differentiated System Description Table</firstterm>
2413         <acronym>DSDT</acronym>) is provided that specifies a
2414         tree-like name space of devices and methods.</para>
2415
2416       <para>The <acronym>ACPI</acronym> driver must parse the fixed
2417         tables, implement an interpreter for the bytecode, and modify
2418         device drivers and the kernel to accept information from the
2419         <acronym>ACPI</acronym> subsystem.  For &os;, Intel has
2420         provided an interpreter (<acronym>ACPI-CA</acronym>) that is
2421         shared with Linux and &netbsd;.
2422
2423         <indexterm><primary>&netbsd;</primary></indexterm>
2424         
2425         The path to the 
2426         <acronym>ACPI-CA</acronym> source code is 
2427         <filename role="directory">src/sys/contrib/dev/acpica-unix-YYYYMMDD</filename>, 
2428         where YYYYMMDD is the release date of the ACPI-CA source code. The 
2429         glue code that allows <acronym>ACPI-CA</acronym> to work on 
2430         &os; is in <filename>src/sys/dev/acpica5/Osd</filename>. Finally, 
2431         drivers that implement various <acronym>ACPI</acronym> devices 
2432         are found in <filename role="directory">src/sys/dev/acpica5</filename>, 
2433         and architecture-dependent code resides in 
2434         <filename role="directory">/sys/<replaceable>arch</replaceable>/acpica5</filename>.
2435       </para>
2436     </sect2>
2437
2438     <sect2 id="ACPI-comprob">
2439       <title>Common Problems</title>
2440
2441       <para>For <acronym>ACPI</acronym> to work correctly, all the parts
2442         have to work correctly.  Here are some common problems, in order
2443         of frequency of appearance, and some possible workarounds or
2444         fixes.</para>
2445
2446       <sect3>
2447         <title>Suspend/Resume</title>
2448
2449         <para><acronym>ACPI</acronym> has three suspend to
2450           <acronym>RAM</acronym> (<acronym>STR</acronym>) states,
2451           <literal>S1</literal>-<literal>S3</literal>, and one suspend
2452           to disk state (<literal>STD</literal>), called
2453           <literal>S4</literal>.  <literal>S5</literal> is
2454           <quote>soft off</quote> and is the normal state your system
2455           is in when plugged in but not powered up.
2456           <literal>S4</literal> can actually be implemented two separate
2457           ways.  <literal>S4</literal><acronym>BIOS</acronym> is a
2458           <acronym>BIOS</acronym>-assisted suspend to disk.
2459           <literal>S4</literal><acronym>OS</acronym> is implemented
2460           entirely by the operating system.</para>
2461
2462         <para>Start by checking <command>sysctl</command>
2463           <option>hw.acpi</option> for the suspend-related items.  Here
2464           are the results for my Thinkpad:</para>
2465
2466         <screen>hw.acpi.supported_sleep_state: S3 S4 S5</screen>
2467         <screen>hw.acpi.s4bios: 0</screen>
2468
2469         <para>This means that I can use <command>acpiconf -s</command>
2470           to test <literal>S3</literal>,
2471           <literal>S4</literal><acronym>OS</acronym>, and
2472           <literal>S5</literal>.  If <option>s4bios</option> was one
2473           (<literal>1</literal>), I would have
2474           <literal>S4</literal><acronym>BIOS</acronym>
2475           support instead of <literal>S4</literal>
2476           <acronym>OS</acronym>.</para>
2477
2478         <para>When testing suspend/resume, start with
2479           <literal>S1</literal>, if supported.  This state is most
2480           likely to work since it doesn't require much driver support.
2481           No one has implemented <literal>S2</literal> but if you have
2482           it, it's similar to <literal>S1</literal>.  The next thing
2483           to try is <literal>S3</literal>.  This is the deepest
2484           <acronym>STR</acronym> state and requires a lot of driver
2485           support to properly reinitialize your hardware.  If you have
2486           problems resuming, feel free to email the &a.bugs.name; list but
2487           do not expect the problem to be resolved since there are a lot
2488           of drivers/hardware that need more testing and work.</para>
2489
2490         <para>To help isolate the problem, remove as many drivers from
2491           your kernel as possible.  If it works, you can narrow down
2492           which driver is the problem by loading drivers until it fails
2493           again.  Typically binary drivers like
2494           <filename>nvidia.ko</filename>, <application>X11</application>
2495           display drivers, and <acronym>USB</acronym> will have the most
2496           problems while Ethernet interfaces usually work fine.  If you
2497           can load/unload the drivers ok, you can automate this by
2498           putting the appropriate commands in
2499           <filename>/etc/rc.suspend</filename> and
2500           <filename>/etc/rc.resume</filename>.  There is a
2501           commented-out example for unloading and loading a driver.  Try
2502           setting <option>hw.acpi.reset_video</option> to zero (0) if
2503           your display is messed up after resume.  Try setting longer or
2504           shorter values for <option>hw.acpi.sleep_delay</option> to see
2505           if that helps.</para>
2506
2507         <para>Another thing to try is load a recent Linux distribution
2508           with <acronym>ACPI</acronym> support and test their
2509           suspend/resume support on the same hardware.  If it works
2510           on Linux, it's likely a &os; driver problem and narrowing down
2511           which driver causes the problems will help us fix the problem.
2512           Note that the <acronym>ACPI</acronym> maintainers do not
2513           usually maintain other drivers (e.g sound,
2514           <acronym>ATA</acronym>, etc.) so any work done on tracking
2515           down a driver problem should probably eventually be posted
2516           to the &a.bugs.name; list and mailed to the driver
2517           maintainer.  If you are feeling adventurous, go ahead and
2518           start putting some debugging &man.printf.3;s in a problematic
2519           driver to track down where in its resume function it
2520           hangs.</para>
2521
2522         <para>Finally, try disabling <acronym>ACPI</acronym> and
2523           enabling <acronym>APM</acronym> instead.  If suspend/resume
2524           works with <acronym>APM</acronym>, you may be better off
2525           sticking with <acronym>APM</acronym>, especially on older
2526           hardware (pre-2000).  It took vendors a while to get
2527           <acronym>ACPI</acronym> support correct and older hardware is
2528           more likely to have <acronym>BIOS</acronym> problems with
2529           <acronym>ACPI</acronym>.</para>
2530       </sect3>
2531
2532       <sect3>
2533         <title>System Hangs (temporary or permanent)</title>
2534
2535         <para>Most system hangs are a result of lost interrupts or an
2536           interrupt storm.  Chipsets have a lot of problems based on how
2537           the <acronym>BIOS</acronym> configures interrupts before boot,
2538           correctness of the <acronym>APIC</acronym>
2539           (<acronym>MADT</acronym>) table, and routing of the
2540           <firstterm>System Control Interrupt</firstterm>
2541           (<acronym>SCI</acronym>).</para>
2542
2543         <para>Interrupt storms can be distinguished from lost interrupts
2544           by checking the output of <command>vmstat -i</command>
2545           and looking at the line that has
2546           <literal>acpi0</literal>.  If the counter is increasing at more
2547           than a couple per second, you have an interrupt storm.  If the
2548           system appears hung, try breaking to <acronym>DDB</acronym>
2549           (<keycombo action="simul"><keycap>CTRL</keycap>
2550           <keycap>ALT</keycap><keycap>ESC</keycap></keycombo> on
2551           console) and type <option>show interrupts</option>.</para>
2552
2553         <para>Your best hope when dealing with interrupt problems is to
2554           try disabling <acronym>APIC</acronym> support with
2555           <literal>hint.apic.0.disabled="1"</literal> in
2556           <filename>loader.conf</filename>.</para>
2557       </sect3>
2558
2559       <sect3>
2560         <title>Panics</title>
2561
2562         <para>Panics are relatively rare for <acronym>ACPI</acronym> and
2563           are the top priority to be fixed.  The first step is to
2564           isolate the steps to reproduce the panic (if possible)
2565           and get a backtrace.  Follow the advice for enabling
2566           <option>options DDB</option> and setting up a serial console
2567           (see <xref linkend="serialconsole-ddb">)
2568           or setting up a &man.dump.8; partition.  You can get a
2569           backtrace in <acronym>DDB</acronym> with
2570           <option>tr</option>.  If you have to handwrite the
2571           backtrace, be sure to at least get the lowest five (5) and top
2572           five (5) lines in the trace.</para>
2573
2574         <para>Then, try to isolate the problem by booting with
2575           <acronym>ACPI</acronym> disabled.  If that works, you can
2576           isolate the <acronym>ACPI</acronym> subsystem by using various
2577           values of <option>debug.acpi.disable</option>.  See the
2578           &man.acpi.4; manual page for some examples.</para>
2579       </sect3>
2580
2581       <sect3>
2582         <title>System Powers Up After Suspend or Shutdown</title>
2583         <para>First, try setting
2584           <option>hw.acpi.disable_on_poweroff=</option><quote>0</quote>
2585           in &man.loader.conf.5;.  This keeps <acronym>ACPI</acronym>
2586           from disabling various events during the shutdown process.
2587           Some systems need this value set to <quote>1</quote> (the
2588           default) for the same reason.  This usually fixes
2589           the problem of a system powering up spontaneously after a
2590           suspend or poweroff.</para>
2591       </sect3>
2592
2593       <sect3>
2594         <title>Other Problems</title>
2595
2596         <para>If you have other problems with <acronym>ACPI</acronym>
2597           (working with a docking station, devices not detected, etc.),
2598           please email a description to the mailing list as well;
2599           however, some of these issues may be related to unfinished
2600           parts of the <acronym>ACPI</acronym> subsystem so they might
2601           take a while to be implemented.  Please be patient and
2602           prepared to test patches we may send you.</para>
2603       </sect3>
2604     </sect2>
2605
2606     <sect2 id="ACPI-aslanddump">
2607       <title><acronym>ASL</acronym>, <command>acpidump</command>, and
2608         <acronym>IASL</acronym></title>
2609
2610       <para>The most common problem is the <acronym>BIOS</acronym>
2611         vendors providing incorrect (or outright buggy!) bytecode.  This
2612         is usually manifested by kernel console messages like
2613         this:</para>
2614
2615       <screen>ACPI-1287: *** Error: Method execution failed [\\_SB_.PCI0.LPC0.FIGD._STA] \\
2616 (Node 0xc3f6d160), AE_NOT_FOUND</screen>
2617
2618       <para>Often, you can resolve these problems by updating your
2619         <acronym>BIOS</acronym> to the latest revision.  Most console
2620         messages are harmless but if you have other problems like
2621         battery status not working, they're a good place to start
2622         looking for problems in the <acronym>AML</acronym>.  The
2623         bytecode, known as <acronym>AML</acronym>, is compiled from a
2624         source language called <acronym>ASL</acronym>.  The
2625         <acronym>AML</acronym> is found in the table known as the
2626         <acronym>DSDT</acronym>.  To get a copy of your
2627         <acronym>ASL</acronym>, use &man.acpidump.8;.  You should use
2628         both the <option>-t</option> (show contents of the fixed tables)
2629         and <option>-d</option> (disassemble <acronym>AML</acronym> to
2630         <acronym>ASL</acronym>) options.  See the
2631         <link linkend="ACPI-submitdebug">Submitting Debugging
2632         Information</link> section for an example syntax.</para>
2633
2634       <para>The simplest first check you can do is to recompile your
2635         <acronym>ASL</acronym> to check for errors.  Warnings can
2636         usually be ignored but errors are bugs that will usually prevent
2637         <acronym>ACPI</acronym> from working correctly.  To recompile
2638         your <acronym>ASL</acronym>, issue the following command:</para>
2639
2640       <screen>&prompt.root; <userinput>iasl your.asl</userinput></screen>
2641     </sect2>
2642
2643     <sect2 id="ACPI-fixasl">
2644       <title>Fixing Your <acronym>ASL</acronym></title>
2645
2646       <para>In the long run, our goal is for almost everyone to have
2647         <acronym>ACPI</acronym> work without any user intervention.  At
2648         this point, however, we are still developing workarounds for
2649         common mistakes made by the <acronym>BIOS</acronym> vendors.
2650         The Microsoft interpreter (<filename>acpi.sys</filename> and
2651         <filename>acpiec.sys</filename>) does not strictly check for
2652         adherence to the standard, and thus many <acronym>BIOS</acronym>
2653         vendors who only test <acronym>ACPI</acronym> under Windows
2654         never fix their <acronym>ASL</acronym>.  We hope to continue to
2655         identify and document exactly what non-standard behavior is
2656         allowed by Microsoft's interpreter and replicate it so &os; can
2657         work without forcing users to fix the <acronym>ASL</acronym>.
2658         As a workaround and to help us identify behavior, you can fix
2659         the <acronym>ASL</acronym> manually.  If this works for you,
2660         please send a &man.diff.1; of the old and new
2661         <acronym>ASL</acronym> so we can possibly work around the buggy
2662         behavior in <acronym>ACPI-CA</acronym> and thus make your fix
2663         unnecessary.</para>
2664
2665       <para>Here is a list of common error messages, their cause, and
2666         how to fix them:</para>
2667
2668       <sect3>
2669         <title>_OS dependencies</title>
2670
2671         <para>Some <acronym>AML</acronym> assumes the world consists of
2672           various Windows versions.  You can tell &os; to claim it is
2673           any <acronym>OS</acronym> to see if this fixes problems you
2674           may have.  An easy way to override this is to set
2675           <option>hw.acpi.osname</option>=<quote>Windows 2001</quote>
2676           in <filename>/boot/loader.conf</filename> or other similar
2677           strings you find in the <acronym>ASL</acronym>.</para>
2678     </sect3>
2679
2680       <sect3>
2681         <title>Missing Return statements</title>
2682
2683         <para>Some methods do not explicitly return a value as the
2684           standard requires.  While <acronym>ACPI-CA</acronym>
2685           does not handle this, &os; has a workaround that allows it to
2686           return the value implicitly.  You can also add explicit
2687           Return statements where required if you know what value should
2688           be returned.  To force <command>iasl</command> to compile the
2689           <acronym>ASL</acronym>, use the <option>-f</option>
2690           flag.</para>
2691       </sect3>
2692
2693       <sect3>
2694         <title>Overriding the Default <acronym>AML</acronym></title>
2695
2696         <para>After you customize <filename>your.asl</filename>, you
2697           will want to compile it, run:</para>
2698
2699         <screen>&prompt.root; <userinput>iasl your.asl</userinput></screen>
2700
2701         <para>You can add the <option>-f</option> flag to force creation
2702           of the <acronym>AML</acronym>, even if there are errors during
2703           compilation.  Remember that some errors (e.g., missing Return
2704           statements) are automatically worked around by the
2705           interpreter.</para>
2706
2707         <para><filename>DSDT.aml</filename> is the default output
2708           filename for <command>iasl</command>.  You can load this
2709           instead of your <acronym>BIOS</acronym>'s buggy copy (which
2710           is still present in flash memory) by editing
2711           <filename>/boot/loader.conf</filename> as
2712           follows:</para>
2713
2714         <programlisting>acpi_dsdt_load="YES"
2715 acpi_dsdt_name="/boot/DSDT.aml"</programlisting>
2716
2717         <para>Be sure to copy your <filename>DSDT.aml</filename> to the
2718           <filename role="directory">/boot</filename> directory.</para>
2719       </sect3>
2720     </sect2>
2721
2722     <sect2 id="ACPI-debugoutput">
2723       <title>Getting Debugging Output From
2724         <acronym>ACPI</acronym></title>
2725
2726       <para>The <acronym>ACPI</acronym> driver has a very flexible
2727         debugging facility.  It allows you to specify a set of subsystems
2728         as well as the level of verbosity.  The subsystems you wish to
2729         debug are specified as <quote>layers</quote> and are broken down
2730         into <acronym>ACPI-CA</acronym> components (ACPI_ALL_COMPONENTS)
2731         and <acronym>ACPI</acronym> hardware support (ACPI_ALL_DRIVERS).
2732         The verbosity of debugging output is specified as the
2733         <quote>level</quote> and ranges from ACPI_LV_ERROR (just report
2734         errors) to ACPI_LV_VERBOSE (everything).  The
2735         <quote>level</quote> is a bitmask so multiple options can be set
2736         at once, separated by spaces.  In practice, you will want to use
2737         a serial console to log the output if it is so long
2738         it flushes the console message buffer.  </para>
2739
2740       <para>Debugging output is not enabled by default.  To enable it,
2741         add <option>options ACPI_DEBUG</option> to your kernel config
2742         if <acronym>ACPI</acronym> is compiled into the kernel.  You can
2743         add <option>ACPI_DEBUG=1</option> to your
2744         <filename>/etc/make.conf</filename> to enable it globally.  If
2745         it is a module, you can recompile just your
2746         <filename>acpi.ko</filename> module as follows:</para>
2747
2748       <screen>&prompt.root; <userinput>cd /sys/dev/acpica5
2749 &amp;&amp; make clean &amp;&amp;
2750 make ACPI_DEBUG=1</userinput></screen>
2751
2752       <para>Install <filename>acpi.ko</filename> in
2753         <filename role="directory">/boot/kernel</filename> and add your
2754         desired level and layer to <filename>loader.conf</filename>.
2755         This example enables debug messages for all
2756         <acronym>ACPI-CA</acronym> components and all
2757         <acronym>ACPI</acronym> hardware drivers
2758         (<acronym>CPU</acronym>, <acronym>LID</acronym>, etc.)  It will
2759         only output error messages, the least verbose level.</para>
2760
2761       <programlisting>debug.acpi.layer="ACPI_ALL_COMPONENTS ACPI_ALL_DRIVERS"
2762 debug.acpi.level="ACPI_LV_ERROR"</programlisting>
2763
2764       <para>If the information you want is triggered by a specific event
2765         (say, a suspend and then resume), you can leave out changes to
2766         <filename>loader.conf</filename> and instead use
2767         <command>sysctl</command> to specify the layer and level after
2768         booting and preparing your system for the specific event.  The
2769         <command>sysctl</command>s are named the same as the tunables
2770         in <filename>loader.conf</filename>.</para>
2771     </sect2>
2772
2773     <sect2 id="ACPI-References">
2774       <title>References</title>
2775
2776       <para>More information about <acronym>ACPI</acronym> may be found
2777         in the following locations:</para>
2778
2779       <itemizedlist>
2780         <listitem>
2781           <para>The &a.freebsd.acpi; (This is FreeBSD-specific; posting 
2782           &os; questions here may not generate much of an answer.)</para>
2783         </listitem>
2784
2785         <listitem>
2786           <para>The <acronym>ACPI</acronym> Mailing List Archives (FreeBSD)
2787             <ulink url="http://lists.freebsd.org/pipermail/freebsd-acpi/"></ulink></para>
2788         </listitem>
2789
2790         <listitem>
2791           <para>The old <acronym>ACPI</acronym> Mailing List Archives (FreeBSD)
2792             <ulink url="http://home.jp.FreeBSD.org/mail-list/acpi-jp/"></ulink></para>
2793         </listitem>
2794
2795         <listitem>
2796           <para>The <acronym>ACPI</acronym> 2.0 Specification
2797             <ulink url="http://acpi.info/spec.htm"></ulink></para>
2798         </listitem>
2799
2800         <listitem>
2801           <para>&os; Manual pages: 
2802             &man.acpidump.8;,
2803             &man.acpiconf.8;, 
2804             &man.acpidb.8;</para>
2805         </listitem>
2806
2807         <listitem>
2808           <para><ulink
2809             url="http://www.cpqlinux.com/acpi-howto.html#fix_broken_dsdt">
2810             <acronym>DSDT</acronym> debugging resource</ulink>.
2811             (Uses Compaq as an example but generally useful.)</para>
2812         </listitem>
2813       </itemizedlist>
2814     </sect2>
2815   </sect1>
2816 </chapter>
2817
2818 <!--
2819      Local Variables:
2820      mode: sgml
2821      sgml-declaration: "../chapter.decl"
2822      sgml-indent-data: t
2823      sgml-omittag: nil
2824      sgml-always-quote-attributes: t
2825      sgml-parent-document: ("../book.sgml" "part" "chapter")
2826      End:
2827 -->