| 1 | <!-- |
| 2 | The FreeBSD Documentation Project |
| 3 | |
| 4 | $FreeBSD: /usr/local/www/cvsroot/FreeBSD/doc/en_US.ISO8859-1/books/handbook/config/chapter.sgml,v 1.169 2004/08/27 12:04:24 blackend Exp $ |
| 5 | $DragonFly: doc/en/books/handbook/config/chapter.sgml,v 1.13 2006/09/17 19:00:04 victor Exp $ |
| 6 | --> |
| 7 | |
| 8 | <chapter id="config-tuning"> |
| 9 | <chapterinfo> |
| 10 | <authorgroup> |
| 11 | <author> |
| 12 | <firstname>Chern</firstname> |
| 13 | <surname>Lee</surname> |
| 14 | <contrib>Written by </contrib> |
| 15 | </author> |
| 16 | </authorgroup> |
| 17 | <authorgroup> |
| 18 | <author> |
| 19 | <firstname>Mike</firstname> |
| 20 | <surname>Smith</surname> |
| 21 | <contrib>Based on a tutorial written by </contrib> |
| 22 | </author> |
| 23 | </authorgroup> |
| 24 | <authorgroup> |
| 25 | <author> |
| 26 | <firstname>Matt</firstname> |
| 27 | <surname>Dillon</surname> |
| 28 | <contrib>Also based on tuning(7) written by </contrib> |
| 29 | </author> |
| 30 | </authorgroup> |
| 31 | </chapterinfo> |
| 32 | |
| 33 | <title>Configuration and Tuning</title> |
| 34 | |
| 35 | <sect1 id="config-synopsis"> |
| 36 | <title>Synopsis</title> |
| 37 | |
| 38 | <indexterm><primary>system configuration</primary></indexterm> |
| 39 | <indexterm><primary>system optimization</primary></indexterm> |
| 40 | |
| 41 | <para>One of the important aspects of &os; is system configuration. |
| 42 | Correct system configuration will help prevent headaches during future upgrades. |
| 43 | This chapter will explain much of the &os; configuration process, |
| 44 | including some of the parameters which |
| 45 | can be set to tune a &os; system. |
| 46 | </para> |
| 47 | |
| 48 | <para>After reading this chapter, you will know: |
| 49 | |
| 50 | <itemizedlist> |
| 51 | <listitem> |
| 52 | <para>How to efficiently work with |
| 53 | file systems and swap partitions.</para> |
| 54 | </listitem> |
| 55 | <listitem> |
| 56 | <para>The basics of <filename>rc.conf</filename> configuration and |
| 57 | <filename>rc.d</filename> startup systems.</para> |
| 58 | </listitem> |
| 59 | <listitem> |
| 60 | <para>How to configure and test a network card.</para> |
| 61 | </listitem> |
| 62 | <listitem> |
| 63 | <para>How to configure virtual hosts on your network devices.</para> |
| 64 | </listitem> |
| 65 | <listitem> |
| 66 | <para>How to use the various configuration files in |
| 67 | <filename>/etc</filename>.</para> |
| 68 | </listitem> |
| 69 | <listitem> |
| 70 | <para>How to tune &os; using <command>sysctl</command> |
| 71 | variables.</para> |
| 72 | </listitem> |
| 73 | <listitem> |
| 74 | <para>How to tune disk performance and modify kernel |
| 75 | limitations.</para> |
| 76 | </listitem> |
| 77 | </itemizedlist> |
| 78 | </para> |
| 79 | |
| 80 | <para>Before reading this chapter, you should: |
| 81 | |
| 82 | <itemizedlist> |
| 83 | <listitem> |
| 84 | <para>Understand &unix; and &os; basics (<xref |
| 85 | linkend="basics">).</para> |
| 86 | </listitem> |
| 87 | <listitem> |
| 88 | <para>Be familiar with the basics of kernel configuration/compilation |
| 89 | (<xref linkend="kernelconfig">).</para> |
| 90 | </listitem> |
| 91 | </itemizedlist> |
| 92 | </para> |
| 93 | </sect1> |
| 94 | |
| 95 | <sect1 id="configtuning-initial"> |
| 96 | <title>Initial Configuration</title> |
| 97 | |
| 98 | <sect2> |
| 99 | <title>Partition Layout</title> |
| 100 | |
| 101 | <indexterm><primary>partition layout</primary></indexterm> |
| 102 | <indexterm> |
| 103 | <primary><filename>/etc</filename></primary> |
| 104 | </indexterm> |
| 105 | <indexterm> |
| 106 | <primary><filename>/var</filename></primary> |
| 107 | </indexterm> |
| 108 | <indexterm> |
| 109 | <primary><filename>/usr</filename></primary> |
| 110 | </indexterm> |
| 111 | |
| 112 | <sect3> |
| 113 | <title>Base Partitions</title> |
| 114 | |
| 115 | <para>When laying out file systems with &man.disklabel.8; |
| 116 | remember that hard |
| 117 | drives transfer data faster from the outer |
| 118 | tracks to the inner. |
| 119 | Thus smaller and heavier-accessed file systems |
| 120 | should be closer to the outside of the drive, while |
| 121 | larger partitions like <filename>/usr</filename> should be placed |
| 122 | toward the inner. It is a good idea to create |
| 123 | partitions in a similar order to: root, swap, |
| 124 | <filename>/var</filename>, <filename>/usr</filename>.</para> |
| 125 | |
| 126 | <para>The size of <filename>/var</filename> |
| 127 | reflects the intended machine usage. |
| 128 | <filename>/var</filename> is used to hold |
| 129 | mailboxes, log files, and printer spools. Mailboxes and log |
| 130 | files can grow to unexpected sizes depending |
| 131 | on how many users exist and how long log |
| 132 | files are kept. Most users would never require a gigabyte, |
| 133 | but remember that <filename>/var/tmp</filename> |
| 134 | must be large enough to contain packages. |
| 135 | </para> |
| 136 | |
| 137 | <para>The <filename>/usr</filename> partition holds much |
| 138 | of the files required to support the system, the &pkgsrc; |
| 139 | collection (recommended) and the source code (optional). |
| 140 | At least 2 gigabytes would be recommended for this partition.</para> |
| 141 | |
| 142 | <para>When selecting partition sizes, keep the space |
| 143 | requirements in mind. Running out of space in |
| 144 | one partition while barely using another can be a |
| 145 | hassle.</para> |
| 146 | |
| 147 | <!-- todo: reed: fix this for the new installer, if it applies |
| 148 | <note><para>Some users have found that &man.sysinstall.8;'s |
| 149 | <literal>Auto-defaults</literal> partition sizer will |
| 150 | sometimes select smaller than adequate <filename>/var</filename> |
| 151 | and <filename>/</filename> partitions. Partition wisely and |
| 152 | generously.</para></note> |
| 153 | --> |
| 154 | |
| 155 | </sect3> |
| 156 | |
| 157 | <sect3 id="swap-design"> |
| 158 | <title>Swap Partition</title> |
| 159 | |
| 160 | <indexterm><primary>swap sizing</primary></indexterm> |
| 161 | <indexterm><primary>swap partition</primary></indexterm> |
| 162 | |
| 163 | <para>As a rule of thumb, the swap partition should be |
| 164 | about double the size of system memory (RAM). For example, |
| 165 | if the machine has 128 megabytes of memory, |
| 166 | the swap file should be 256 megabytes. Systems with |
| 167 | less memory may perform better with more swap. |
| 168 | Less than 256 megabytes of swap is not recommended and |
| 169 | memory expansion should be considered. |
| 170 | The kernel's VM paging algorithms are tuned to |
| 171 | perform best when the swap partition is at least two times the |
| 172 | size of main memory. Configuring too little swap can lead to |
| 173 | inefficiencies in the VM page scanning code and might create |
| 174 | issues later if more memory is added.</para> |
| 175 | |
| 176 | <para>On larger systems with multiple SCSI disks (or |
| 177 | multiple IDE disks operating on different controllers), it is |
| 178 | recommend that a swap is configured on each drive (up |
| 179 | to four drives). The swap partitions should be |
| 180 | approximately the same size. The kernel can handle arbitrary |
| 181 | sizes but internal data structures scale to 4 times the |
| 182 | largest swap partition. Keeping the swap partitions near the |
| 183 | same size will allow the kernel to optimally stripe swap space |
| 184 | across disks. |
| 185 | Large swap sizes are fine, even if swap is not |
| 186 | used much. It might be easier to recover |
| 187 | from a runaway program before being forced to reboot.</para> |
| 188 | </sect3> |
| 189 | |
| 190 | <sect3> |
| 191 | <title>Why Partition?</title> |
| 192 | |
| 193 | <para>Several users think a single large partition will be fine, |
| 194 | but there are several reasons why this is a bad idea. |
| 195 | First, each partition has different operational |
| 196 | characteristics and separating them allows the file system to |
| 197 | tune accordingly. For example, the root |
| 198 | and <filename>/usr</filename> partitions are read-mostly, without |
| 199 | much writing. While a lot of reading and writing could |
| 200 | occur in <filename>/var</filename> and |
| 201 | <filename>/var/tmp</filename>.</para> |
| 202 | |
| 203 | <para>By properly partitioning a system, fragmentation |
| 204 | introduced in the smaller write heavy partitions |
| 205 | will not bleed over into the mostly-read partitions. |
| 206 | Keeping the write-loaded partitions closer to |
| 207 | the disk's edge, |
| 208 | will |
| 209 | increase I/O performance in the partitions where it occurs |
| 210 | the most. Now while I/O |
| 211 | performance in the larger partitions may be needed, |
| 212 | shifting them more toward the edge of the disk will not |
| 213 | lead to a significant performance improvement over moving |
| 214 | <filename>/var</filename> to the edge. |
| 215 | Finally, there are safety concerns. A smaller, neater root |
| 216 | partition which is mostly read-only has a greater |
| 217 | chance of surviving a bad crash.</para> |
| 218 | </sect3> |
| 219 | </sect2> |
| 220 | |
| 221 | </sect1> |
| 222 | |
| 223 | <sect1 id="configtuning-core-configuration"> |
| 224 | <title>Core Configuration</title> |
| 225 | |
| 226 | <indexterm> |
| 227 | <primary>rc files</primary> |
| 228 | <secondary><filename>rc.conf</filename></secondary> |
| 229 | </indexterm> |
| 230 | |
| 231 | <para>The principal location for system configuration information |
| 232 | is within <filename>/etc/rc.conf</filename>. This file |
| 233 | contains a wide range of configuration information, principally |
| 234 | used at system startup to configure the system. Its name |
| 235 | directly implies this; it is configuration information for the |
| 236 | <filename>rc*</filename> files.</para> |
| 237 | |
| 238 | <para>An administrator should make entries in the |
| 239 | <filename>rc.conf</filename> file to |
| 240 | override the default settings from |
| 241 | <filename>/etc/defaults/rc.conf</filename>. The defaults file |
| 242 | should not be copied verbatim to <filename>/etc</filename> - it |
| 243 | contains default values, not examples. All system-specific |
| 244 | changes should be made in the <filename>rc.conf</filename> |
| 245 | file itself.</para> |
| 246 | |
| 247 | <para>A number of strategies may be applied in clustered |
| 248 | applications to separate site-wide configuration from |
| 249 | system-specific configuration in order to keep administration |
| 250 | overhead down. The recommended approach is to place site-wide |
| 251 | configuration into another file, |
| 252 | such as <filename>/etc/rc.conf.site</filename>, and then include |
| 253 | this file into <filename>/etc/rc.conf</filename>, which will |
| 254 | contain only system-specific information.</para> |
| 255 | |
| 256 | <para>As <filename>rc.conf</filename> is read by &man.sh.1; it is |
| 257 | trivial to achieve this. For example:</para> |
| 258 | |
| 259 | <itemizedlist> |
| 260 | <listitem><para>rc.conf:</para> |
| 261 | <programlisting> . rc.conf.site |
| 262 | hostname="node15.example.com" |
| 263 | network_interfaces="fxp0 lo0" |
| 264 | ifconfig_fxp0="inet 10.1.1.1"</programlisting></listitem> |
| 265 | <listitem><para>rc.conf.site:</para> |
| 266 | <programlisting> defaultrouter="10.1.1.254" |
| 267 | saver="daemon" |
| 268 | blanktime="100"</programlisting></listitem> |
| 269 | </itemizedlist> |
| 270 | |
| 271 | <para>The <filename>rc.conf.site</filename> file can then be |
| 272 | distributed to every system using <command>rsync</command> or a |
| 273 | similar program, while the <filename>rc.conf</filename> file |
| 274 | remains unique.</para> |
| 275 | |
| 276 | <para>Upgrading the system using |
| 277 | <command>make world</command> will not overwrite the |
| 278 | <filename>rc.conf</filename> |
| 279 | file, so system configuration information will not be lost.</para> |
| 280 | |
| 281 | </sect1> |
| 282 | |
| 283 | <sect1 id="configtuning-appconfig"> |
| 284 | <title>Application Configuration</title> |
| 285 | |
| 286 | <para>Typically, installed applications have their own |
| 287 | configuration files, with their own syntax, etc. It is |
| 288 | important that these files be kept separate from the base |
| 289 | system, so that they may be easily located and managed by the |
| 290 | package management tools.</para> |
| 291 | |
| 292 | <indexterm><primary>/usr/pkg/etc</primary></indexterm> |
| 293 | |
| 294 | <para>Typically, these files are installed in |
| 295 | <filename>/usr/pkg/etc</filename>. In the case where an |
| 296 | application has a large number of configuration files, a |
| 297 | subdirectory will be created to hold them.</para> |
| 298 | |
| 299 | <para>Normally, when a port or package is installed, sample |
| 300 | configuration files are also installed. These are usually 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> |
| 305 | |
| 306 | <para>For example, consider the contents of the directory |
| 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 |
| 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 | |
| 328 | <indexterm><primary>/usr/pkg/etc/rc.d</primary></indexterm> |
| 329 | |
| 330 | <para>Software installed from a port or the packages collection |
| 331 | will often place a script in |
| 332 | <filename>/usr/pkg/etc/rc.d</filename> which is invoked at |
| 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 |
| 344 | <filename>/usr/pkg/etc/rc.d</filename> looks like:</para> |
| 345 | |
| 346 | <programlisting>#!/bin/sh |
| 347 | echo -n ' FooBar' |
| 348 | |
| 349 | case "$1" in |
| 350 | start) |
| 351 | /usr/pkg/bin/foobar |
| 352 | ;; |
| 353 | stop) |
| 354 | kill -9 `cat /var/run/foobar.pid` |
| 355 | ;; |
| 356 | *) |
| 357 | echo "Usage: `basename $0` {start|stop}" >&2 |
| 358 | exit 64 |
| 359 | ;; |
| 360 | esac |
| 361 | |
| 362 | exit 0 |
| 363 | </programlisting> |
| 364 | |
| 365 | <para>The startup scripts of &os; will look in |
| 366 | <filename>/usr/pkg/etc/rc.d</filename> for scripts that have an |
| 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 |
| 374 | <filename>/usr/pkg/etc/rc.d</filename> and make sure it is |
| 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 |
| 389 | in <filename>/etc/rc.local</filename> (which does not exist by default). |
| 390 | Note that <filename>rc.local</filename> is |
| 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 |
| 397 | <filename>/usr/pkg/etc/rc.d</filename> instead.</para> |
| 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 | |
| 463 | <!-- todo: add up-to-date crontab --> |
| 464 | <programlisting># /etc/crontab - root's crontab for &os; |
| 465 | # |
| 466 | # <co id="co-comments"> |
| 467 | # |
| 468 | SHELL=/bin/sh |
| 469 | PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin <co id="co-env"> |
| 470 | HOME=/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. |
| 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> |
| 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 | |
| 603 | <title>Using rc under &os;</title> |
| 604 | |
| 605 | <indexterm><primary>rcNG</primary></indexterm> |
| 606 | |
| 607 | <para>&os; uses the &netbsd; |
| 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 |
| 665 | from the <command>rc.d</command> script, not a |
| 666 | <username>root</username> prompt.</para> |
| 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> |
| 674 | sshd 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 | |
| 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. |
| 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> |
| 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. |
| 718 | |
| 719 | <footnote> |
| 720 | <para>Previously this was used to define *BSD dependent features. |
| 721 | </para></footnote> |
| 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. |
| 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> |
| 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 | |
| 739 | <para>Additional information about the &os; |
| 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> |
| 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: <82c169 PNIC 10/100BaseTX> port 0xa000-0xa0ff mem 0xd3800000-0xd38 |
| 794 | 000ff irq 15 at device 11.0 on pci0 |
| 795 | dc0: Ethernet address: 00:a0:cc:da:da:da |
| 796 | miibus0: <MII bus> on dc0 |
| 797 | ukphy0: <Generic IEEE 802.3u media interface> on miibus0 |
| 798 | ukphy0: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto |
| 799 | dc1: <82c169 PNIC 10/100BaseTX> port 0x9800-0x98ff mem 0xd3000000-0xd30 |
| 800 | 000ff irq 11 at device 12.0 on pci0 |
| 801 | dc1: Ethernet address: 00:a0:cc:da:da:db |
| 802 | miibus1: <MII bus> on dc1 |
| 803 | ukphy1: <Generic IEEE 802.3u media interface> on miibus1 |
| 804 | ukphy1: 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 |
| 833 | card needs to be configured. As with many other things, the |
| 834 | network card may have been configured at installation time.</para> |
| 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> |
| 840 | dc0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> 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 <full-duplex>) |
| 844 | status: active |
| 845 | dc1: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> 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 |
| 850 | lp0: flags=8810<POINTOPOINT,SIMPLEX,MULTICAST> mtu 1500 |
| 851 | lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> mtu 16384 |
| 852 | inet 127.0.0.1 netmask 0xff000000 |
| 853 | tun0: flags=8010<POINTOPOINT,MULTICAST> mtu 1500</screen> |
| 854 | |
| 855 | <note> |
| 856 | <para>Note that entries concerning IPv6 |
| 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 |
| 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> |
| 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 | <full-duplex>)</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 |
| 942 | an Ethernet cable is not plugged into the card.</para> |
| 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<BROADCAST,SIMPLEX,MULTICAST> 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 |
| 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 | |
| 963 | <para>Manually configuring the card has the disadvantage that you |
| 964 | would have to do it after each reboot of the system. The file |
| 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" |
| 973 | ifconfig_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> |
| 1023 | PING 192.168.1.3 (192.168.1.3): 56 data bytes |
| 1024 | 64 bytes from 192.168.1.3: icmp_seq=0 ttl=64 time=0.082 ms |
| 1025 | 64 bytes from 192.168.1.3: icmp_seq=1 ttl=64 time=0.074 ms |
| 1026 | 64 bytes from 192.168.1.3: icmp_seq=2 ttl=64 time=0.076 ms |
| 1027 | 64 bytes from 192.168.1.3: icmp_seq=3 ttl=64 time=0.108 ms |
| 1028 | 64 bytes from 192.168.1.3: icmp_seq=4 ttl=64 time=0.076 ms |
| 1029 | |
| 1030 | --- 192.168.1.3 ping statistics --- |
| 1031 | 5 packets transmitted, 5 packets received, 0% packet loss |
| 1032 | round-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> |
| 1037 | PING 192.168.1.2 (192.168.1.2): 56 data bytes |
| 1038 | 64 bytes from 192.168.1.2: icmp_seq=0 ttl=64 time=0.726 ms |
| 1039 | 64 bytes from 192.168.1.2: icmp_seq=1 ttl=64 time=0.766 ms |
| 1040 | 64 bytes from 192.168.1.2: icmp_seq=2 ttl=64 time=0.700 ms |
| 1041 | 64 bytes from 192.168.1.2: icmp_seq=3 ttl=64 time=0.747 ms |
| 1042 | 64 bytes from 192.168.1.2: icmp_seq=4 ttl=64 time=0.704 ms |
| 1043 | |
| 1044 | --- 192.168.1.2 ping statistics --- |
| 1045 | 5 packets transmitted, 5 packets received, 0% packet loss |
| 1046 | round-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 |
| 1067 | your version of &os; to the latest PREVIEW version. Check the |
| 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 | |
| 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). |
| 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 |
| 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> |
| 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 |
| 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> |
| 1171 | |
| 1172 | <para>The following entries configure the adapter correctly for |
| 1173 | this arrangement:</para> |
| 1174 | |
| 1175 | <programlisting> ifconfig_fxp0="inet 10.1.1.1 netmask 255.255.255.0" |
| 1176 | ifconfig_fxp0_alias0="inet 10.1.1.2 netmask 255.255.255.255" |
| 1177 | ifconfig_fxp0_alias1="inet 10.1.1.3 netmask 255.255.255.255" |
| 1178 | ifconfig_fxp0_alias2="inet 10.1.1.4 netmask 255.255.255.255" |
| 1179 | ifconfig_fxp0_alias3="inet 10.1.1.5 netmask 255.255.255.255" |
| 1180 | ifconfig_fxp0_alias4="inet 202.0.75.17 netmask 255.255.255.240" |
| 1181 | ifconfig_fxp0_alias5="inet 202.0.75.18 netmask 255.255.255.255" |
| 1182 | ifconfig_fxp0_alias6="inet 202.0.75.19 netmask 255.255.255.255" |
| 1183 | ifconfig_fxp0_alias7="inet 202.0.75.20 netmask 255.255.255.255"</programlisting> |
| 1184 | |
| 1185 | </sect1> |
| 1186 | |
| 1187 | <sect1 id="configtuning-configfiles"> |
| 1188 | <title>Configuration Files</title> |
| 1189 | |
| 1190 | <sect2> |
| 1191 | <title><filename>/etc</filename> Layout</title> |
| 1192 | <para>There are a number of directories in which configuration |
| 1193 | information is kept. These include:</para> |
| 1194 | |
| 1195 | <informaltable frame="none"> |
| 1196 | <tgroup cols="2"> |
| 1197 | <colspec colwidth="1*"> |
| 1198 | <colspec colwidth="2*"> |
| 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> |
| 1227 | <entry><filename>/usr/pkg/etc</filename></entry> |
| 1228 | <entry>Configuration files for installed applications. |
| 1229 | May contain per-application subdirectories.</entry> |
| 1230 | </row> |
| 1231 | <row> |
| 1232 | <entry><filename>/usr/pkg/etc/rc.d</filename></entry> |
| 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"> |
| 1267 | <colspec colwidth="1*"> |
| 1268 | <colspec colwidth="2*"> |
| 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 |
| 1292 | nameserver 147.11.1.11 |
| 1293 | nameserver 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 | |
| 1318 | <programlisting># |
| 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 |
| 1328 | 127.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 | |
| 1377 | <programlisting># |
| 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 |
| 1386 | security.* /var/log/security |
| 1387 | mail.info /var/log/maillog |
| 1388 | lpr.info /var/log/lpd-errs |
| 1389 | cron.* /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 | |
| 1409 | <!-- todo: reed: this should be documented in book --> |
| 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 |
| 1437 | # |
| 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 | |
| 1457 | <!-- todo: reed: this should be documented in book --> |
| 1458 | <para>Consult the &man.newsyslog.8; manual page for more |
| 1459 | information.</para> |
| 1460 | </sect3> |
| 1461 | </sect2> |
| 1462 | |
| 1463 | <sect2 id="configtuning-sysctlconf"> |
| 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) |
| 1480 | compat.linux.osname: Linux |
| 1481 | compat.linux.osrelease: 2.4.2</programlisting> |
| 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> |
| 1512 | kern.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> |
| 1519 | kern.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 | |
| 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 | |
| 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 |
| 1551 | device_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 | |
| 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 |
| 1609 | related sysctls. We do not recommend modifying these values. |
| 1610 | The VM system does an extremely good job of |
| 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 | |
| 1647 | <para>IDE drives lie about when a write completes. With IDE write |
| 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 |
| 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 |
| 1658 | boot loader at boot time. Attempting to do it after the |
| 1659 | kernel boots will have no effect.</para> |
| 1660 | |
| 1661 | <para>For more information, please see &man.ata.4; manual page.</para> |
| 1662 | </sect3> |
| 1663 | |
| 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 | |
| 1684 | <note><para>It is possible to enable Soft Updates |
| 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 |
| 1690 | recommend to use Soft Updates on all of your file systems but |
| 1691 | <filename>/</filename>. There |
| 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; |
| 1816 | needs to be run at a later time.</para> |
| 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 | |
| 1885 | <note><para>Setting <option>MAXUSERS</option> to |
| 1886 | <literal>0</literal> in your kernel configuration file will choose |
| 1887 | a reasonable default value based on the amount of RAM present in |
| 1888 | your system. It is set to 0 in the default GENERIC kernel.</para></note> |
| 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 | |
| 1916 | <para>The <literal>NMBCLUSTERS</literal> kernel configuration |
| 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 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 K receive |
| 1925 | and 16 K send buffer, you need approximately 32 MB worth of |
| 1926 | network buffers to cover the web server. A good rule of thumb is |
| 1927 | to multiply by 2, so 2x32 MB / 2 KB = |
| 1928 | 64 MB / 2 kB = 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 |
| 1934 | use. <varname>kern.ipc.nmbclusters</varname> loader tunable should |
| 1935 | be used to tune this at boot time.</para> |
| 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 |
| 1940 | <literal>NSFBUFS</literal> kernel configuration option or by |
| 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 |
| 1944 | in the <literal>sfbufa</literal> state. The sysctl |
| 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 — 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 |
| 1999 | TCP/Vegas in NetBSD. |
| 2000 | |
| 2001 | <indexterm><primary>&netbsd;</primary></indexterm> |
| 2002 | |
| 2003 | It can be |
| 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 |
| 2061 | discussion about swap space in <xref linkend="configtuning-initial"> |
| 2062 | for some suggestions on how to best arrange your swap.</para> |
| 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 |
| 2069 | local hard disk to swap to. Even though &os; has an excellent |
| 2070 | NFS implementation, NFS swapping will be limited |
| 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> |
| 2084 | <title>Creating a Swapfile</title> |
| 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> |
| 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 | |
| 2161 | <para>In this section, we will provide |
| 2162 | comprehensive information about <acronym>ACPI</acronym>. References |
| 2163 | will be provided for further reading at the end. Please be aware |
| 2164 | that <acronym>ACPI</acronym> is available on &os; systems as a |
| 2165 | default kernel module. </para> |
| 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 |
| 2179 | current Plug and Play interfaces (such as APM), prior to the introduction of |
| 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 |
| 2307 | &a.bugs.name;</para> |
| 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 > <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 | |
| 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 |
| 2385 | shared with Linux and &netbsd;. |
| 2386 | |
| 2387 | <indexterm><primary>&netbsd;</primary></indexterm> |
| 2388 | |
| 2389 | The path to the |
| 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> |
| 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 |
| 2450 | problems resuming, feel free to email the &a.bugs.name; list but |
| 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 |
| 2480 | to the &a.bugs.name; list and mailed to the driver |
| 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 | |
| 2579 | <screen>ACPI-1287: *** Error: Method execution failed [\\_SB_.PCI0.LPC0.FIGD._STA] \\ |
| 2580 | (Node 0xc3f6d160), AE_NOT_FOUND</screen> |
| 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> |
| 2642 | </sect3> |
| 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" |
| 2679 | acpi_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> |
| 2684 | </sect2> |
| 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 |
| 2702 | it flushes the console message buffer. </para> |
| 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 | |
| 2712 | <screen>&prompt.root; <userinput>cd /sys/dev/acpica5 |
| 2713 | && make clean && |
| 2714 | make 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" |
| 2726 | debug.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> |
| 2745 | <para>The &a.freebsd.acpi; (This is FreeBSD-specific; posting |
| 2746 | &os; questions here may not generate much of an answer.)</para> |
| 2747 | </listitem> |
| 2748 | |
| 2749 | <listitem> |
| 2750 | <para>The <acronym>ACPI</acronym> Mailing List Archives (FreeBSD) |
| 2751 | <ulink url="http://lists.freebsd.org/pipermail/freebsd-acpi/"></ulink></para> |
| 2752 | </listitem> |
| 2753 | |
| 2754 | <listitem> |
| 2755 | <para>The old <acronym>ACPI</acronym> Mailing List Archives (FreeBSD) |
| 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> |
| 2765 | <para>&os; Manual pages: |
| 2766 | &man.acpidump.8;, |
| 2767 | &man.acpiconf.8;, |
| 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 | --> |