en/books/handbook/config/chapter.sgml

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