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