Change links to https
[ikiwiki.git] / docs / handbook / Configuration / index.mdwn
1 # Configuration and Tuning 
2
3 ***Originally written by Chern Lee.  Based on a tutorial written by Mike Smith.  Also based on [tuning(7)](http://leaf.dragonflybsd.org/cgi/web-man?command=tuning&section7) written by Matt Dillon.***
4
5 [[!toc  levels=3]]
6
7 ##Synopsis 
8
9 One of the more important aspects of DragonFly is system configuration. Correct system configuration helps prevent headaches and ensures that the system runs smoothly under loaded conditions. This chapter will explain much of the DragonFly configuration process, including some of the parameters which can be set to tune a DragonFly system.
10
11 After reading this chapter, you will know:
12
13 * How to efficiently work with file systems and swap partitions.
14
15 * The basics of `rc.conf` configuration and `rc.d` startup systems.
16
17 * How to configure and test a network card.
18
19 * How to configure virtual hosts on your network devices.
20
21 * How to use the various configuration files in `/etc`.
22
23 * How to tune DragonFly using `sysctl` variables.
24
25 * How to tune disk performance and modify kernel limitations.
26
27 ## Initial Configuration 
28
29 ### Partition Layout 
30
31 #### Base Partitions 
32
33 Typically all partitions related to a DragonFly system are configured with [disklabel(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel&section=8) .  In the old days major subsystem directories such as /var and /usr were placed in their own partition, but in modern times nearly everything is just loaded onto the root filesystem.
34
35 By convention, partitions are configured as follows:  a: boot, b: swap, and d: root, and the disklabel is placed in slice 1 of the drive whether it is formatted with [fdisk(8)] (http://leaf.dragonflybsd.org/cgi/web-man?command=fdisk&section=8) or with [gpt(8)] (http://leaf.dragonflybsd.org/cgi/web-man?command=gpt&section=8).  For legacy boot, drives are formatted with [fdisk(8)] and for UEFI boot drives are formatted with [gpt(8)] and slice 0 contains the msdos gpt filesystem.  The initial formatting of the drive can be mostly automated up to the point where you install a disklabel, see the respective manual pages.
36
37 Sometimes it is useful to separate data you wish to backup from data that you do not wish to backup.  By convention, on DragonFly, data that you do not wish to backup would be placed in e: build, mounted on /build, with sub-directories 'var.crash', 'usr.obj' 'var.tmp', 'tmp', and so forth which you use fstab to null-mount onto their normal locations of '/var/crash', '/usr/obj', '/var/tmp', and '/tmp'.  Remember that /var/tmp and /tmp must be chmod'd with the sticky bit set, i.e. 1777.
38
39 Also by convention, the normal way to have a '/tmp' and a '/var/tmp' is to specify them as TMPFS filesystems in '/etc/fstab' rather than directories on the drive.  At least '/tmp' anyhow. '/var/tmp' is supposed to be somewhat persistent but it doesn't have to be.
40
41 When selecting partition sizes, keep the space requirements in mind. Running out of space in one partition while barely using another can be a hassle.  We recommend the following sizes:
42
43     a: 1g   4.2BSD (i.e. UFS)  /boot
44     b: <approx-2x-system-ram>  swap
45     d: * HAMMER or HAMMER2     root (/)
46
47 We recommend a 1 gigabyte boot partition, a swap partition approximately 2x system memory, with some caveats (see below) and then a root partition that holds the remainder of the drive.  If you use the additional e: /build convention, we recommend not skimping on either the root partition or the /build partition, but the larger one really depends on your intentions.  For example, if you intend to hold a large project on the system and do not wish for it to reside on /root, you might decide to use /build for that and leave things like /tmp and /var/tmp and such on root.  It's really up to you.
48
49 #### Swap Partition 
50
51 As a rule of thumb, the swap partition should be about double the size of system memory (RAM). For example, if the machine has 4g (gigabytes) of memory, the swap file should be around 8g. Systems with less memory may perform better with more swap.  Systems with huge amounts of memory, however, do not necessarily need to have 2x system ram as swap space.  We recommend at least 1x system memory to allow dumps to work in such cases.
52
53 If your storage space is severely limited, definitely specify less swap than the recommendation so you have space for the normal filesystems.  However, very tiny amounts of swap on systems with large amounts of ram may cause degenerate paging behavior so do not make the swap partition too small.
54
55 Swap is best served on fast media such as a SSD.  If you have multiple SSDs, then spreading your swap space across them will result in higher paging performance.  Note that swap is generally allocated linearly and often not heavily used.  This is actually optimal for use on a SSD because all that unused space can be automatically trimmed on boot using the 'trim' option as part of the fstab line for the swap setup.  TRIM is dangerous and must be enabled via sysctl as well for this to work.  But since swap tends to be used sparingly, having most of its space pre-trimmed means the SSD can use it as spare space to improve wear leveling.
56
57 If swap is not expected to be used heavily, just swapping to one device is perfectly fine.
58
59 DragonFly can accommodate huge amounts of swap, hundreds of gigabytes or even more if desired.  Large amounts of swap are typically only configured when using the [swapcache(8)]
60 (http://leaf.dragonflybsd.org/cgi/web-man?command=swapcache&section=8) feature, described later.
61
62
63 #### Why Partition? 
64
65 On modern systems the disk is formatted with GPT slices.  GPT can accomodate individual slices per filesystem, but it isn't really convenient to edit and display, and the DragonFly disklabel has certain advantages in that it will automatically align partitions on physical 1MB boundaries regardless of whether the disklabel itself is aligned in the slice it was placed in.
66
67 The Convention for DragonFly is thus to put DragonFly related partitions in a disklabel as previously described, in slice 1, and not spread them out onto different GPT slices.  This puts everyone on the same page when dealing with maintenance of the system.
68
69 CategoryHandbook
70
71 CategoryHandbook-configuration
72
73 ## Core Configuration 
74
75 The principal location for system configuration information is within `/etc/rc.conf`. This file contains a wide range of configuration information, principally used at system startup to configure the system. Its name directly implies this; it is configuration information for the `rc*` files.
76
77 An administrator should make entries in the `rc.conf` file to override the default settings from `/etc/defaults/rc.conf`. The defaults file should not be copied verbatim to `/etc` - it contains default values, not examples. All system-specific changes should be made in the `rc.conf` file itself.
78
79 A number of strategies may be applied in clustered applications to separate site-wide configuration from system-specific configuration in order to keep administration overhead down. The recommended approach is to place site-wide configuration into another file, such as `/etc/rc.conf.site`, and then include this file into `/etc/rc.conf`, which will contain only system-specific information.
80
81 As `rc.conf` is read by [sh(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=sh&section=1) it is trivial to achieve this. For example:
82
83 * rc.conf:
84
85         hostname="node15.example.com"
86
87         network_interfaces="fxp0 lo0"
88
89         ifconfig_fxp0="inet 10.1.1.1"
90
91   
92
93 * rc.conf.site: 
94
95         defaultrouter="10.1.1.254"
96
97         saver="daemon"
98
99         blanktime="100"
100
101   
102
103 The `rc.conf.site` file can then be distributed to every system using `rsync` or a similar program, while the `rc.conf` file remains unique.
104
105 Upgrading the system using `make world` will not overwrite the `rc.conf` file, so system configuration information will not be lost.
106
107 CategoryHandbook
108
109 CategoryHandbook-configuration
110
111 ## Application Configuration 
112
113 Typically, installed applications have their own configuration files, with their own syntax, etc. It is important that these files be kept separate from the base system, so that they may be easily located and managed by the package management tools.
114
115 Typically, these files are installed in `/usr/local/etc`. In the case where an application has a large number of configuration files, a subdirectory will be created to hold them.
116
117 Normally, when a port or package is installed, sample configuration files are also installed. These are usually identified with a `.default` suffix. If there are no existing configuration files for the application, they will be created by copying the `.default` files.
118
119 For example, consider the contents of the directory `/usr/local/etc/apache24`:
120
121     
122
123     total 90
124
125     -rw-r--r--  1 root  wheel  -   34K Jan 11 12:04 httpd.conf
126
127     -rw-r--r--  1 root  wheel  -   13K Jan 11 12:02 magic
128
129     -rw-r--r--  1 root  wheel  -   28K Jan 11 12:02 mime.types
130
131     -rw-r--r--  1 root  wheel  -   11K Jan 11 12:02 ssl.conf
132
133     
134     
135     
136     
137     
138
139 ## Starting Services 
140
141 It is common for a system to host a number of services. These may be started in several different fashions, each having different advantages.
142
143 Software installed from a port or the packages collection will often place a script in `/usr/local/etc/rc.d` which is invoked at system startup with a `start` argument, and at system shutdown with a `stop` argument. This is the recommended way for starting system-wide services that are to be run as `root`, or that expect to be started as `root`. These scripts are registered as part of the installation of the package, and will be removed when the package is removed.  This directory is automatically searched by the RC system and you can enable installed packages at boot from `/etc/rc.conf` the same way you enable system services.
144
145 A generic startup script in `/usr/local/etc/rc.d` looks like:
146
147     
148
149     #!/bin/sh
150
151     echo -n ' FooBar'
152
153     
154
155     case "$1" in
156
157     start)
158
159             /usr/local/bin/foobar
160
161             ;;
162
163     stop)
164
165             kill -9 `cat /var/run/foobar.pid`
166
167             ;;
168
169     
170 *)
171
172             echo "Usage: `basename $0` {start|stop}" >&2
173
174             exit 64
175
176             ;;
177
178     esac
179
180     
181
182     exit 0
183
184     
185
186 You can make a shell script executable with [chmod(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=chmod&section=1) as shown below:
187
188     
189
190     # chmod 755 "FooBar.sh"
191
192 Some services expect to be invoked by [inetd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=inetd&section=8) when a connection is received on a suitable port. This is common for mail reader servers (POP and IMAP, etc.). These services are enabled by editing the file `/etc/inetd.conf`. See [inetd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=inetd&section=8) for details on editing this file.
193
194 Some additional system services may not be covered by the toggles in `/etc/rc.conf`. These are traditionally enabled by placing the command(s) to invoke them in `/etc/rc.local` (which does not exist by default). Note that `rc.local` is generally regarded as the location of last resort; if there is a better place to start a service, do it there.
195
196  **Note:** Do ***not*** place any commands in `/etc/rc.conf`. To start daemons, or run any commands at boot time, place a script in `/usr/local/etc/rc.d` instead, or put special command sequences in `/etc/rc.local`, depending on the situation.
197
198 It is also possible to use the [cron(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=cron&section=8) daemon to start system services. This approach has a number of advantages, not least being that because [cron(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=cron&section=8) runs these processes as the owner of the `crontab`, services may be started and maintained by non-`root` users.
199
200 This takes advantage of a feature of [cron(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=cron&section=8): the time specification may be replaced by `@reboot`, which will cause the job to be run when [cron(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=cron&section=8) is started shortly after system boot.
201
202 CategoryHandbook
203
204 CategoryHandbook-configuration
205
206 ## Configuring the cron Utility 
207
208 ***Contributed by Tom Rhodes. ***
209
210 One of the most useful utilities in DragonFly is [cron(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=cron&section=8). The `cron` utility runs in the background and constantly checks the `/etc/crontab` file. The `cron` utility also checks the `/var/cron/tabs` directory, in search of new `crontab` files. These `crontab` files store information about specific functions which `cron` is supposed to perform at certain times.
211
212 The `cron` utility uses two different types of configuration files, the system crontab and user crontabs. The only difference between these two formats is the sixth field. In the system crontab, the sixth field is the name of a user for the command to run as. This gives the system crontab the ability to run commands as any user. In a user crontab, the sixth field is the command to run, and all commands run as the user who created the crontab; this is an important security feature.
213
214  **Note:** User crontabs allow individual users to schedule tasks without the need for root privileges. Commands in a user's crontab run with the permissions of the user who owns the crontab.
215
216 The `root` user can have a user crontab just like any other user. This one is different from `/etc/crontab` (the system crontab). Because of the system crontab, there's usually no need to create a user crontab for `root`.
217
218 Let us take a look at the `/etc/crontab` file (the system crontab):
219
220     
221
222     # /etc/crontab - root's crontab for DragonFly
223
224     #
225
226     #                                                                  (1)
227
228     #
229
230     SHELL=/bin/sh
231
232     PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin                            (2)
233
234     HOME=/var/log
235
236     #
237
238     #
239
240     #minute     hour    mday    month   wday    who     command            (3)
241
242     #
243
244     #
245
246     
247     */5 *       *       *       *       root    /usr/libexec/atrun (4)
248
249  1. Like most DragonFly configuration files, the `#` character represents a comment. A comment can be placed in the file as a reminder of what and why a desired action is performed. Comments cannot be on the same line as a command or else they will be interpreted as part of the command; they must be on a new line. Blank lines are ignored.
250
251  1. First, the environment must be defined. The equals (`=`) character is used to define any environment settings, as with this example where it is used for the `SHELL`, `PATH`, and `HOME` options. If the shell line is omitted, `cron` will use the default, which is `sh`. If the `PATH` variable is omitted, no default will be used and file locations will need to be absolute. If `HOME` is omitted, `cron` will use the invoking users home directory.
252
253  1. This line defines a total of seven fields. Listed here are the values `minute`, `hour`, `mday`, `month`, `wday`, `who`, and `command`. These are almost all self explanatory. `minute` is the time in minutes the command will be run. `hour` is similar to the `minute` option, just in hours. `mday` stands for day of the month. `month` is similar to `hour` and `minute`, as it designates the month. The `wday` option stands for day of the week. All these fields must be numeric values, and follow the twenty-four hour clock. The `who` field is special, and only exists in the `/etc/crontab` file. This field specifies which user the command should be run as. When a user installs his or her `crontab` file, they will not have this option. Finally, the `command` option is listed. This is the last field, so naturally it should designate the command to be executed.
254
255  1. This last line will define the values discussed above. Notice here we have a `*/5` listing, followed by several more `*` characters. These `*` characters mean ***first-last***, and can be interpreted as ***every*** time. So, judging by this line, it is apparent that the `atrun` command is to be invoked by `root` every five minutes regardless of what day or month it is. For more information on the `atrun` command, see the [atrun(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=atrun&section=8) manual page.Commands can have any number of flags passed to them; however, commands which extend to multiple lines need to be broken with the backslash ***\*** continuation character.
256
257 This is the basic set up for every `crontab` file, although there is one thing different about this one. Field number six, where we specified the username, only exists in the system `/etc/crontab` file. This field should be omitted for individual user `crontab` files.
258
259 ### Installing a Crontab 
260
261  **Important:** You must not use the procedure described here to edit/install the system crontab. Simply use your favorite editor: the `cron` utility will notice that the file has changed and immediately begin using the updated version. If you use `crontab` to load the `/etc/crontab` file you may get an error like `root: not found` because of the system crontab's additional user field.
262
263 To install a freshly written user `crontab`, first use your favorite editor to create a file in the proper format, and then use the `crontab` utility. The most common usage is:
264
265     
266
267     % crontab crontab-file
268
269 In this example, `crontab-file` is the filename of a `crontab` that was previously created.
270
271 There is also an option to list installed `crontab` files: just pass the `-l` option to `crontab` and look over the output.
272
273 For users who wish to begin their own crontab file from scratch, without the use of a template, the `crontab -e` option is available. This will invoke the selected editor with an empty file. When the file is saved, it will be automatically installed by the `crontab` command.
274
275 If you later want to remove your user `crontab` completely, use `crontab` with the `-r` option.
276
277 ## Using rc under DragonFly 
278
279 ***Contributed by Tom Rhodes. ***
280
281 DragonFly uses the NetBSD® `rc.d` system for system initialization. Users should notice the files listed in the `/etc/rc.d` directory. Many of these files are for basic services which can be controlled with the `start`, `stop`, and `restart` options. For instance, [sshd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=sshd&section=8&manpath=OpenBSD+3.3) can be restarted with the following command:
282
283     
284
285     # /etc/rc.d/sshd restart
286
287 This procedure is similar for other services. Of course, services are usually started automatically as specified in [rc.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=rc.conf&section=5). For example, enabling the Network Address Translation daemon at startup is as simple as adding the following line to `/etc/rc.conf`:
288
289     natd_enable="YES"
290
291 If a `natd_enable="NO"` line is already present, then simply change the `NO` to `YES`. The rc scripts will automatically load any other dependent services during the next reboot, as described below.
292
293 Another way to add services to the automatic startup/shutdown is to type, for example for `natd`,
294
295      # rcenable natd
296
297 Since the `rc.d` system is primarily intended to start/stop services at system startup/shutdown time, the standard `start`, `stop` and `restart` options will only perform their action if the appropriate `/etc/rc.conf` variables are set. For instance the above `sshd restart` command will only work if `sshd_enable` is set to `YES` in `/etc/rc.conf`. To `start`, `stop` or `restart` a service regardless of the settings in `/etc/rc.conf`, the commands should be prefixed with ***force***. For instance to restart `sshd` regardless of the current `/etc/rc.conf` setting, execute the following command:
298
299     
300
301     # /etc/rc.d/sshd forcerestart
302
303 It is easy to check if a service is enabled in `/etc/rc.conf` by running the appropriate `rc.d` script with the option `rcvar`. Thus, an administrator can check that `sshd` is in fact enabled in `/etc/rc.conf` by running:
304
305     
306
307     # /etc/rc.d/sshd rcvar
308
309     # sshd
310
311     $sshd_enable=YES
312
313  **Note:** The second line (`# sshd`) is the output from the `rc.d` script, not a `root` prompt.
314
315 To determine if a service is running, a `status` option is available. For instance to verify that `sshd` is actually started:
316
317     
318
319     # /etc/rc.d/sshd status
320
321     sshd is running as pid 433.
322
323 It is also possible to `reload` a service. This will attempt to send a signal to an individual service, forcing the service to reload its configuration files. In most cases this means sending the service a `SIGHUP` signal.
324
325 The  **rcNG**  structure is used both for network services and system initialization. Some services are run only at boot; and the RCNG system is what triggers them.
326
327 Many system services depend on other services to function properly. For example, NIS and other RPC-based services may fail to start until after the `rpcbind` (portmapper) service has started. To resolve this issue, information about dependencies and other meta-data is included in the comments at the top of each startup script. The [rcorder(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rcorder&section=8) program is then used to parse these comments during system initialization to determine the order in which system services should be invoked to satisfy the dependencies. The following words may be included at the top of each startup file:
328
329 * `PROVIDE`: Specifies the services this file provides.
330
331 * `REQUIRE`: Lists services which are required for this service. This file will run ***after*** the specified services.
332
333 * `BEFORE`: Lists services which depend on this service. This file will run ***before*** the specified services.
334
335 * KEYWORD: When [rcorder(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rcorder&section=8) uses the `-k` option, then only the rc.d files matching this keyword are used. [(1)](#FTN.AEN4751) For example, when using `-k shutdown`, only the `rc.d` scripts defining the `shutdown` keyword are used.
336
337   With the `-s` option, [rcorder(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rcorder&section=8) will skip any `rc.d` script defining the corresponding keyword to skip. For example, scripts defining the `nostart` keyword are skipped at boot time.
338
339 By using this method, an administrator can easily control system services without the hassle of ***runlevels*** like some other UNIX® operating systems.
340
341 Additional information about the DragonFly `rc.d` system can be found in the [rc(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rc&section=8), [rc.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=rc.conf&section=5), and [rc.subr(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rc.subr&section=8) manual pages.
342
343 ### Using DragonFly's rcrun(8) 
344
345 Besides the methods described above DragonFly supports [rcrun(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rcrun&section=8) to control rc(8) scripts.  [rcrun(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rcrun&section=8) provides a number of command for controlling rc(8)
346
347 scripts.  The ***start***, ***forcestart***, ***faststart***, ***stop***, ***restart***, and ***rcvar*** commands are just passed to the scripts.  See rc(8) for more information on these commands.
348
349 The remaining commands are:
350
351 [[!table  data="""
352   **disable**  | Sets the corresponding `_enable` variable in rc.conf(5) to ***NO*** and runs the stop command. 
353   **enable**   | Sets the corresponding `_enable` variable in rc.conf(5) to ***YES*** and runs the start command. 
354   **list**  | Shows the status of the specified scripts.  If no argument is specified, the status of all scripts is shown. |
355
356 """]]
357
358 To enable the [dntpd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=dntpd&section=8) service, you can use:
359
360      # rcenable dntpd
361      
362  
363
364 To check if [dntpd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=dntpd&section=8) is running you can use the following command:
365
366     
367
368     # rclist dntpd
369
370     rcng_dntpd=stopped
371
372 To start [dntpd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=dntpd&section=8):
373
374     
375
376     # rcstart dntpd
377
378     Running /etc/rc.d/dntpd start
379
380     Starting dntpd.
381
382 Restart and stop works the same way:
383
384     
385
386     # rcrestart dntpd
387
388     Stopping dntpd.
389
390     Starting dntpd.
391
392     
393
394     # rcstop dntpd
395
396     Stopping dntpd.
397
398 If a service is not enabled in `/etc/rc.conf`, but you want it start anyway, execute the following:
399
400     
401
402     # rcforce dntpd
403
404     Running /etc/rc.d/dntpd forcestart
405
406     Starting dntpd.
407
408 #### Notes 
409
410 [[!table  data="""
411 <tablestyle="width:100%"> [(1)](configtuning-rcng.html#AEN4751) | Previously this was used to define *BSD dependent features.
412 | |
413
414 """]]
415
416 ## Setting Up Network Interface Cards 
417
418 ***Contributed by Marc Fonvieille. ***
419
420 Nowadays we can not think about a computer without thinking about a network connection. Adding and configuring a network card is a common task for any DragonFly administrator.
421
422 ### Locating the Correct Driver 
423
424 Most common network chipsets are built into the kernel by default and will simply show up when
425 you run the `ifconfig` command.  In situations where the NIC does not show up, if the chipset is supported by DragonFly, you may have to load the appropriate driver using `kldload if_<blah>` and see if it shows up.  You can load modules at boot time by putting the line `<modulename>_load="YES"` in `/boot/loader.conf`.  For example `if_emx_load="YES"`.  Available drivers can be found using ls as follows: `ls /boot/kernel/if*.ko`.
426
427 If you have doubts about which driver is the correct one, read the manual page of the driver. The manual page will give you more information about the supported hardware and even the possible problems that could occur.
428
429 In this example, we see that two cards using the [em(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=em&section=4) driver are present on the system.
430
431 ### Configuring the Network Card 
432
433 Once the right driver is loaded for the network card, the card needs to be configured. As with many other things, the network card may have been configured at installation time.
434
435 To display the configuration for the network interfaces on your system, enter the following command:
436
437     
438
439     % ifconfig
440
441     em0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
442
443             inet 192.168.1.3 netmask 0xffffff00 broadcast 192.168.1.255
444
445             ether 00:a0:cc:da:da:da
446
447             media: Ethernet autoselect (100baseTX <full-duplex>)
448
449             status: active
450
451     em1: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
452
453             inet 10.0.0.1 netmask 0xffffff00 broadcast 10.0.0.255
454
455             ether 00:a0:cc:da:da:db
456
457             media: Ethernet 10baseT/UTP
458
459             status: no carrier
460
461     lp0: flags=8810<POINTOPOINT,SIMPLEX,MULTICAST> mtu 1500
462
463     lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> mtu 16384
464
465             inet 127.0.0.1 netmask 0xff000000
466
467     tun0: flags=8010<POINTOPOINT,MULTICAST> mtu 1500
468
469  **Note:** Note that entries concerning IPv6 (`inet6` etc.) were omitted in this example.
470
471 In this example, the following devices were displayed:
472
473 * `em0`: The first Ethernet interface
474
475 * `em1`: The second Ethernet interface
476
477 * `lp0`: The parallel port interface
478
479 * `lo0`: The loopback device
480
481 * `tun0`: The tunnel device used by  **ppp** 
482
483 DragonFly uses the driver name followed by the order in which one the card is detected at the kernel boot to name the network card, starting the count at zero. For example, `sis2` would be the third network card on the system using the [sis(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=sis&section=4) driver.
484
485 In this example, the `em0` device is up and running. The key indicators are:
486
487   1. `UP` means that the card is configured and ready.
488
489   1. The card has an Internet (`inet`) address (in this case `192.168.1.3`).
490
491   1. It has a valid subnet mask (`netmask`; `0xffffff00` is the same as `255.255.255.0`).
492
493   1. It has a valid broadcast address (in this case, `192.168.1.255`).
494
495   1. The MAC address of the card (`ether`) is `00:a0:cc:da:da:da`
496
497   1. The physical media selection is on autoselection mode (`media: Ethernet autoselect (100baseTX <full-duplex>)`). We see that `dc1` was configured to run with `10baseT/UTP` media. For more information on available media types for a driver, please refer to its manual page.
498
499   1. The status of the link (`status`) is `active`, i.e. the carrier is detected. For `dc1`, we see `status: no carrier`. This is normal when an Ethernet cable is not plugged into the card.
500
501 If the [ifconfig(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=ifconfig&section=8) output had shown something similar to:
502
503     
504
505     em0: flags=8843<BROADCAST,SIMPLEX,MULTICAST> mtu 1500
506
507                 ether 00:a0:cc:da:da:da
508
509 it would indicate the card has not been configured.
510
511 To configure your card, you need `root` privileges. The network card configuration can be done from the command line with [ifconfig(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=ifconfig&section=8) as root.
512
513     
514
515     # ifconfig em0 inet 192.168.1.3 netmask 255.255.255.0
516
517 Manually configuring the care has the disadvantage that you would have to do it after each reboot of the system. The file `/etc/rc.conf` is where to add the network card's configuration.
518
519 Open `/etc/rc.conf` in your favorite editor. You need to add a line for each network card present on the system, for example in our case, we added these lines:
520
521     
522
523     ifconfig_em0="inet 192.168.1.3 netmask 255.255.255.0"
524
525     ifconfig_em1="inet 10.0.0.1 netmask 255.255.255.0 media 10baseT/UTP"
526
527 You have to replace `em0`, `em1`, and so on, with the correct device for your cards, and the addresses with the proper ones. You should read the card driver and [ifconfig(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#ifconfig&section8) manual pages for more details about the allowed options and also [rc.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=rc.conf&section=5) manual page for more information on the syntax of `/etc/rc.conf`.
528
529 If you configured the network during installation, some lines about the network card(s) may be already present. Double check `/etc/rc.conf` before adding any lines.
530
531 You may also have to edit the file `/etc/hosts` to add the names and the IP addresses of various machines of the LAN, if they are not already there. For more information please refer to [hosts(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=hosts&section=5) and to `/usr/share/examples/etc/hosts`.  The use of `/etc/hosts` is not encouraged.  Instead, a DNS resolver should be specified in `/etc/resolv.conf` (see the manual page for /etc/resolv.conf).
532
533 ### Testing and Troubleshooting 
534
535 Once you have made the necessary changes in `/etc/rc.conf`, you should reboot your system. This will allow the change(s) to the interface(s) to be applied, and verify that the system restarts without any configuration errors.
536
537 Once the system has been rebooted, you should test the network interfaces.
538
539 #### Testing the Ethernet Card 
540
541 To verify that an Ethernet card is configured correctly, you have to try two things. First, ping the interface itself, and then ping another machine on the LAN.
542
543 First test the local interface:
544
545     
546
547     % ping -c5 192.168.1.3
548
549     PING 192.168.1.3 (192.168.1.3): 56 data bytes
550
551     64 bytes from 192.168.1.3: icmp_seq#0 ttl64 time=0.082 ms
552
553     64 bytes from 192.168.1.3: icmp_seq#1 ttl64 time=0.074 ms
554
555     64 bytes from 192.168.1.3: icmp_seq#2 ttl64 time=0.076 ms
556
557     64 bytes from 192.168.1.3: icmp_seq#3 ttl64 time=0.108 ms
558
559     64 bytes from 192.168.1.3: icmp_seq#4 ttl64 time=0.076 ms
560
561     
562
563     --- 192.168.1.3 ping statistics ---
564
565     5 packets transmitted, 5 packets received, 0% packet loss
566
567     round-trip min/avg/max/stddev = 0.074/0.083/0.108/0.013 ms
568
569 Now we have to ping another machine on the LAN:
570
571     
572
573     % ping -c5 192.168.1.2
574
575     PING 192.168.1.2 (192.168.1.2): 56 data bytes
576
577     64 bytes from 192.168.1.2: icmp_seq#0 ttl64 time=0.726 ms
578
579     64 bytes from 192.168.1.2: icmp_seq#1 ttl64 time=0.766 ms
580
581     64 bytes from 192.168.1.2: icmp_seq#2 ttl64 time=0.700 ms
582
583     64 bytes from 192.168.1.2: icmp_seq#3 ttl64 time=0.747 ms
584
585     64 bytes from 192.168.1.2: icmp_seq#4 ttl64 time=0.704 ms
586
587     
588
589     --- 192.168.1.2 ping statistics ---
590
591     5 packets transmitted, 5 packets received, 0% packet loss
592
593     round-trip min/avg/max/stddev = 0.700/0.729/0.766/0.025 ms
594
595 You could also use the machine name instead of `192.168.1.2` if you have set up the `/etc/hosts` file.
596
597 #### Troubleshooting 
598
599 Troubleshooting hardware and software configurations is always a pain, and a pain which can be alleviated by checking the simple things first. Is your network cable plugged in? Have you properly configured the network services? Did you configure the firewall correctly? Is the card you are using supported by DragonFly? Always check the hardware notes before sending off a bug report. Update your version of DragonFly to the latest PREVIEW version. Check the mailing list archives, or perhaps search the Internet.
600
601 If the card works, yet performance is poor, it would be worthwhile to read over the [tuning(7)](http://leaf.dragonflybsd.org/cgi/web-man?command=tuning&section=7) manual page. You can also check the network configuration as incorrect network settings can cause slow connections.  Under DragonFly, network interfaces universally default to a highest-performance configuration, but extreme network conditions may require some tuning for optimal results.
602
603 Some users experience one or two ***device timeouts***, which is normal for some cards. If they continue, or are bothersome, you may wish to be sure the device is not conflicting with another device. Double check the cable connections. Perhaps you may just need to get another card.
604
605 At times, users see a few ***`watchdog timeout`*** errors. The first thing to do here is to check your network cable. Many cards require a PCI slot which supports Bus Mastering. On some old motherboards, only one PCI slot allows it (usually slot 0). Check the network card and the motherboard documentation to determine if that may be the problem.
606
607 ***`No route to host`*** messages occur if the system is unable to route a packet to the destination host. This can happen if no default route is specified, or if a cable is unplugged. Check the output of `netstat -rn` and make sure there is a valid route to the host you are trying to reach. If there is not, read on to [advanced-networking.html Chapter 19].
608
609 ***`ping: sendto: Permission denied`*** error messages are often caused by a misconfigured firewall. If `ipfw` is enabled in the kernel but no rules have been defined, then the default policy is to deny all traffic, even ping requests! Read on to [firewalls.html Section 10.7] for more information.
610
611 Sometimes performance of the card is poor, or below average. In these cases it is best to set the media selection mode from `autoselect` to the correct media selection. While this usually works for most hardware, it may not resolve this issue for everyone. Again, check all the network settings, and read over the [tuning(7)](http://leaf.dragonflybsd.org/cgi/web-man?command=tuning&section=7) manual page.
612
613 ## Virtual Hosts 
614
615 A very common use of DragonFly is virtual site hosting, where one server appears to the network as many servers. This is achieved by assigning multiple network addresses to a single interface.
616
617 A given network interface has one ***real*** address, and may have any number of ***alias*** addresses. These aliases are normally added by placing alias entries in `/etc/rc.conf`.
618
619 An alias entry for the interface `fxp0` looks like:
620
621     
622
623     ifconfig_fxp0_alias0="inet xxx.xxx.xxx.xxx netmask xxx.xxx.xxx.xxx"
624
625 Note that alias entries must start with `alias0` and proceed upwards in order, (for example, `_alias1`, `_alias2`, and so on). The configuration process will stop at the first missing number.
626
627 The calculation of alias netmasks is important, but fortunately quite simple. For a given interface, there must be one address which correctly represents the network's netmask. Any other addresses which fall within this network must have a netmask of all `1`s (expressed as either `255.255.255.255` or `0xffffffff`).
628
629 For example, consider the case where the `fxp0` interface is connected to two networks, the `10.1.1.0` network with a netmask of `255.255.255.0` and the `202.0.75.16` network with a netmask of `255.255.255.240`. We want the system to appear at `10.1.1.1` through `10.1.1.5` and at `202.0.75.17` through `202.0.75.20`. As noted above, only the first address in a given network range (in this case, `10.0.1.1` and `202.0.75.17`) should have a real netmask; all the rest (`10.1.1.2` through `10.1.1.5` and `202.0.75.18` through `202.0.75.20`) must be configured with a netmask of `255.255.255.255`.
630
631 The following entries configure the adapter correctly for this arrangement:
632
633     
634
635      ifconfig_fxp0="inet 10.1.1.1 netmask 255.255.255.0"
636
637      ifconfig_fxp0_alias0="inet 10.1.1.2 netmask 255.255.255.255"
638
639      ifconfig_fxp0_alias1="inet 10.1.1.3 netmask 255.255.255.255"
640
641      ifconfig_fxp0_alias2="inet 10.1.1.4 netmask 255.255.255.255"
642
643      ifconfig_fxp0_alias3="inet 10.1.1.5 netmask 255.255.255.255"
644
645      ifconfig_fxp0_alias4="inet 202.0.75.17 netmask 255.255.255.240"
646
647      ifconfig_fxp0_alias5="inet 202.0.75.18 netmask 255.255.255.255"
648
649      ifconfig_fxp0_alias6="inet 202.0.75.19 netmask 255.255.255.255"
650
651      ifconfig_fxp0_alias7="inet 202.0.75.20 netmask 255.255.255.255"
652
653 CategoryHandbook
654
655 CategoryHandbook-configuration
656
657 ## Configuration Files 
658
659 ### /etc Layout 
660
661 There are a number of directories in which configuration information is kept. These include:
662
663 [[!table  data="""
664  `/etc` | Generic system configuration information; data here is system-specific. 
665  `/etc/defaults` | Default versions of system configuration files. 
666  `/etc/mail` | Extra [sendmail(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=sendmail&section=8) configuration, other MTA configuration files. 
667  `/etc/ppp` | Configuration for both user- and kernel-ppp programs. 
668  `/etc/namedb` | Default location for [named(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=named&section=8) data. Normally `named.conf` and zone files are stored here. 
669  `/usr/local/etc` | Configuration files for installed applications. May contain per-application subdirectories. 
670  `/usr/local/etc/rc.d` | Start/stop scripts for installed applications. 
671  `/var/db` | Automatically generated system-specific database files, such as the package database, the locate database, and so on |
672
673 """]]
674
675 ### Hostnames 
676
677 #### /etc/resolv.conf 
678
679 `/etc/resolv.conf` dictates how DragonFly's resolver accesses the Internet Domain Name System (DNS).
680
681 The most common entries to `resolv.conf` are:
682
683 [[!table  data="""
684  `nameserver` | The IP address of a name server the resolver should query. The servers are queried in the order listed with a maximum of three.
685  `search` | Search list for hostname lookup. This is normally determined by the domain of the local hostname. 
686  `domain` | The local domain name. |
687
688 """]]
689
690 A typical `resolv.conf`:
691
692     
693
694     search example.com
695
696     nameserver 147.11.1.11
697
698     nameserver 147.11.100.30
699
700  **Note:** Only one of the `search` and `domain` options should be used.
701
702 If you are using DHCP, [dhclient(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=dhclient&section=8) usually rewrites `resolv.conf` with information received from the DHCP server.
703
704 #### /etc/hosts 
705
706 `/etc/hosts` is a simple text database reminiscent of the old Internet. It works in conjunction with DNS and NIS providing name to IP address mappings. Local computers connected via a LAN can be placed in here for simplistic naming purposes instead of setting up a [named(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=named&section=8) server. Additionally, `/etc/hosts` can be used to provide a local record of Internet names, reducing the need to query externally for commonly accessed names.  We do not recommend using this file.  DNS is the better choice for most purposes.
707
708     
709
710     #
711
712     #
713
714     # Host Database
715
716     # This file should contain the addresses and aliases
717
718     # for local hosts that share this file.
719
720     # In the presence of the domain name service or NIS, this file may
721
722     # not be consulted at all; see /etc/nsswitch.conf for the resolution order.
723
724     #
725
726     #
727
728     ::1                     localhost localhost.my.domain myname.my.domain
729
730     127.0.0.1               localhost localhost.my.domain myname.my.domain
731
732     #
733
734     # Imaginary network.
735
736     #10.0.0.2               myname.my.domain myname
737
738     #10.0.0.3               myfriend.my.domain myfriend
739
740     #
741
742     # According to RFC 1918, you can use the following IP networks for
743
744     # private nets which will never be connected to the Internet:
745
746     #
747
748     #       10.0.0.0        -   10.255.255.255
749
750     #       172.16.0.0      -   172.31.255.255
751
752     #       192.168.0.0     -   192.168.255.255
753
754     #
755
756     # In case you want to be able to connect to the Internet, you need
757
758     # real official assigned numbers.  PLEASE PLEASE PLEASE do not try
759
760     # to invent your own network numbers but instead get one from your
761
762     # network provider (if any) or from the Internet Registry (ftp to
763
764     # rs.internic.net, directory `/templates').
765
766     #
767
768 `/etc/hosts` takes on the simple format of:
769
770     
771
772     [Internet address] [official hostname] [alias1] [alias2] ...
773
774 For example:
775
776     
777
778     10.0.0.1 myRealHostname.example.com myRealHostname foobar1 foobar2
779
780 Consult [hosts(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=hosts&section=5) for more information.
781
782 ### Log File Configuration 
783
784 #### syslog.conf 
785
786 `syslog.conf` is the configuration file for the [syslogd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=syslogd&section=8) program. It indicates which types of `syslog` messages are logged to particular log files.
787
788     
789
790     #
791
792     #
793
794     #       Spaces ARE valid field separators in this file. However,
795
796     #       other *nix-like systems still insist on using tabs as field
797
798     #       separators. If you are sharing this file between systems, you
799
800     #       may want to use only tabs as field separators here.
801
802     #       Consult the syslog.conf(5) manual page.
803
804     
805 *.err;kern.debug;auth.notice;mail.crit          /dev/console
806
807     *.notice;kern.debug;lpr.info;mail.crit;news.err /var/log/messages
808
809     security.*                                      /var/log/security
810
811     mail.info                                       /var/log/maillog
812
813     lpr.info                                        /var/log/lpd-errs
814
815     cron.*                                          /var/log/cron
816
817     
818 *.err                                           root
819
820     *.notice;news.err                               root
821
822     *.alert                                         root
823
824     *.emerg                                         *
825
826     # uncomment this to log all writes to /dev/console to /var/log/console.log
827
828     #console.info                                   /var/log/console.log
829
830     # uncomment this to enable logging of all log messages to /var/log/all.log
831
832     #*.*                                            /var/log/all.log
833
834     # uncomment this to enable logging to a remote log host named loghost
835
836     #*.*                                            @loghost
837
838     # uncomment these if you're running inn
839
840     # news.crit                                     /var/log/news/news.crit
841
842     # news.err                                      /var/log/news/news.err
843
844     # news.notice                                   /var/log/news/news.notice
845
846     !startslip
847
848     
849 *.*                                             /var/log/slip.log
850
851     !ppp
852
853     
854 *.*                                             /var/log/ppp.log
855
856 Consult the [syslog.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=syslog.conf&section=5) manual page for more information.
857
858 #### newsyslog.conf 
859
860 `newsyslog.conf` is the configuration file for [newsyslog(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=newsyslog&section=8), a program that is normally scheduled to run by [cron(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=cron&section=8). [newsyslog(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=newsyslog&section=8) determines when log files require archiving or rearranging. `logfile` is moved to `logfile.0`, `logfile.0` is moved to `logfile.1`, and so on. Alternatively, the log files may be archived in [gzip(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=gzip&section=1) format causing them to be named: `logfile.0.gz`, `logfile.1.gz`, and so on.
861
862 `newsyslog.conf` indicates which log files are to be managed, how many are to be kept, and when they are to be touched. Log files can be rearranged and/or archived when they have either reached a certain size, or at a certain periodic time/date.
863
864     
865
866     # configuration file for newsyslog
867
868     #
869
870     #
871
872     # filename          [owner:group]    mode count size when [ZB] [/pid_file] [sig_num]
873
874     /var/log/cron                           600  3     100  *     Z
875
876     /var/log/amd.log                        644  7     100  *     Z
877
878     /var/log/kerberos.log                   644  7     100  *     Z
879
880     /var/log/lpd-errs                       644  7     100  *     Z
881
882     /var/log/maillog                        644  7     *    @T00  Z
883
884     /var/log/sendmail.st                    644  10    *    168   B
885
886     /var/log/messages                       644  5     100  *     Z
887
888     /var/log/all.log                        600  7     *    @T00  Z
889
890     /var/log/slip.log                       600  3     100  *     Z
891
892     /var/log/ppp.log                        600  3     100  *     Z
893
894     /var/log/security                       600  10    100  *     Z
895
896     /var/log/wtmp                           644  3     *    @01T05 B
897
898     /var/log/daily.log                      640  7     *    @T00  Z
899
900     /var/log/weekly.log                     640  5     1    $W6D0 Z
901
902     /var/log/monthly.log                    640  12    *    $M1D0 Z
903
904     /var/log/console.log                    640  5     100  *     Z
905
906 Consult the [newsyslog(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=newsyslog&section=8) manual page for more information.
907
908 ### sysctl.conf 
909
910 `sysctl.conf` looks much like `rc.conf`. Values are set in a `variable=value` form. The specified values are set after the system goes into multi-user mode. Not all variables are settable in this mode.
911
912 A sample `sysctl.conf` turning off logging of fatal signal exits and letting Linux programs know they are really running under DragonFly:
913
914     
915
916     kern.logsigexit=0       # Do not log fatal signal exits (e.g. sig 11)
917
918     compat.linux.osname=DragonFly
919
920     compat.linux.osrelease=4.3-STABLE
921
922     
923     
924     
925     
926     
927 ## Tuning with sysctl 
928
929 [sysctl(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=sysctl&section=8) is an interface that allows you to make changes to a running DragonFly system. This includes many advanced options of the TCP/IP stack and virtual memory system that can dramatically improve performance for an experienced system administrator. Over five hundred system variables can be read and set using [sysctl(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=sysctl&section=8).
930
931 At its core, [sysctl(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=sysctl&section=8) serves two functions: to read and to modify system settings.
932
933 To view all readable variables:
934
935     
936
937     % sysctl -a
938
939 To read a particular variable, for example, `kern.maxproc`:
940
941     
942
943     % sysctl kern.maxproc
944
945     kern.maxproc: 1044
946
947 To set a particular variable, use the intuitive `***variable***`=`***value***` syntax:
948
949     
950
951     # sysctl kern.maxfiles=5000
952
953     kern.maxfiles: 2088 -< 5000
954
955 Settings of sysctl variables are usually either strings, numbers, or booleans (a boolean being `1` for yes or a `0` for no).
956
957 If you want to set automatically some variables each time the machine boots, add them to the `/etc/sysctl.conf` file. For more information see the [sysctl.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=sysctl.conf&section=5) manual page and the [configtuning-configfiles.html#CONFIGTUNING-SYSCTLCONF Section 6.10.4].
958
959 ### sysctl(8) Read-only 
960
961 ***Contributed by Tom Rhodes. ***
962
963 In some cases it may be desirable to modify read-only [sysctl(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=sysctl&section=8) values. While this is not recommended, it is also sometimes unavoidable.
964
965 For instance on some laptop models the [cardbus(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=cardbus&section=4) device will not probe memory ranges, and fail with errors which look similar to:
966
967     
968
969     cbb0: Could not map register memory
970
971     device_probe_and_attach: cbb0 attach returned 12
972
973 Cases like the one above usually require the modification of some default [sysctl(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=sysctl&section=8) settings which are set read only. To overcome these situations a user can put [sysctl(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=sysctl&section=8) ***OIDs*** in their local `/boot/loader.conf`. Default settings are located in the `/boot/defaults/loader.conf` file.
974
975 Fixing the problem mentioned above would require a user to set `hw.pci.allow_unsupported_io_range=1` in the aforementioned file. Now [cardbus(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=cardbus&section=4) will work properly.
976
977 ## Tuning Disks 
978
979 ### Sysctl Variables 
980
981 #### `vfs.write_behind` 
982
983 The `vfs.write_behind` sysctl variable defaults to `1` (on). This tells the file system to issue media writes as full clusters are collected, which typically occurs when writing large sequential files. The idea is to avoid saturating the buffer cache with dirty buffers when it would not benefit I/O performance. However, this may stall processes and under certain circumstances you may wish to turn it off.
984
985 #### `vfs.hirunningspace` 
986
987 The `vfs.hirunningspace` sysctl variable determines how much outstanding write I/O may be queued to disk controllers system-wide at any given instance. The default is usually sufficient but on machines with lots of disks you may want to bump it up to four or five ***megabytes***. Note that setting too high a value (exceeding the buffer cache's write threshold) can lead to extremely bad clustering performance. Do not set this value arbitrarily high! Higher write values may add latency to reads occurring at the same time.
988
989 There are various other buffer-cache and VM page cache related sysctls. We do not recommend modifying these values. The VM system does an extremely good job of automatically tuning itself.
990
991 #### `vm.swap_idle_enabled` 
992
993 The `vm.swap_idle_enabled` sysctl variable is useful in large multi-user systems where you have lots of users entering and leaving the system and lots of idle processes. Such systems tend to generate a great deal of continuous pressure on free memory reserves. Turning this feature on and tweaking the swapout hysteresis (in idle seconds) via `vm.swap_idle_threshold1` and `vm.swap_idle_threshold2` allows you to depress the priority of memory pages associated with idle processes more quickly then the normal pageout algorithm. This gives a helping hand to the pageout daemon. Do not turn this option on unless you need it, because the tradeoff you are making is essentially pre-page memory sooner rather than later; thus eating more swap and disk bandwidth. In a small system this option will have a determinable effect but in a large system that is already doing moderate paging this option allows the VM system to stage whole processes into and out of memory easily.
994
995 This option should only be used when default paging activities are insufficient.
996
997 #### kern.cam.da.0.trim_enabled
998
999 AHCI storage devices on which you wish to allow TRIM operations must have trim enabled via the associated sysctl.
1000
1001 #### dev.ahci.0.0.link_pwr_mgmt
1002
1003 On laptops, link power management can reduce power consumption at the cost of slow reaction time when coming out of idle.  This will show up under the dev.ahci sysctl family.  If enabling link power management results in instability or freezes you should not enable the option.
1004
1005
1006 ## Tuning Kernel Limits 
1007
1008 ### File/Process Limits 
1009
1010 #### `kern.maxfiles` 
1011
1012 `kern.maxfiles` can be raised or lowered based upon your system requirements. This variable indicates the maximum number of file descriptors on your system. When the file descriptor table is full, ***`file: table is full`*** will show up repeatedly in the system message buffer, which can be viewed with the `dmesg` command.
1013
1014 Each open file, socket, or fifo uses one file descriptor. A large-scale production server may easily require many thousands of file descriptors, depending on the kind and number of services running concurrently.
1015
1016 `kern.maxfile`'s default value is dictated by available system memory and is typically very generous.
1017
1018 #### `kern.ipc.somaxconn` 
1019
1020 The `kern.ipc.somaxconn` sysctl variable limits the size of the listen queue for accepting new TCP connections. The default value of `128` is typically too low for robust handling of new connections in a heavily loaded web server environment. For such environments, it is recommended to increase this value to `1024` or higher. The service daemon may itself limit the listen queue size (e.g. [sendmail(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=sendmail&section=8), or  **Apache** ) but will often have a directive in its configuration file to adjust the queue size. Large listen queues also do a better job of avoiding Denial of Service (DoS) attacks.
1021
1022 ### Network Limits
1023
1024 The `kern.ipc.nmbclusters` and `kern.ipc.nmbjclusters` tunables (placed in `/boot/loader.conf`) can be used to override the default number of normal clusters and jumbo clusters the network is allowed to use.  Default values are typically based on system memory and quite generous.
1025
1026 A heavily-trafficked server with a low number of Mbufs will hinder DragonFly's ability. Each cluster represents approximately 2 K of memory, so a value of 1024 represents 2 megabytes of kernel memory reserved for network buffers. A simple calculation can be done to figure out how many are needed. If you have a web server which maxes out at 1000 simultaneous connections, and each connection eats a 16 K receive and 16 K send buffer, you need approximately 32 MB worth of network buffers to cover the web server. A good rule of thumb is to multiply by 2, so 2x32 MB / 2 KB # 64 MB / 2 kB  32768.
1027
1028 Under no circumstances should you specify an arbitrarily high value for this parameter as it could lead to a boot time crash or run the system out of memory. The `-m` option to [netstat(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=netstat&section=1) may be used to observe network cluster use. `kern.ipc.nmbclusters` loader tunable should be used to tune this at boot time.
1029
1030 The `kern.ipc.nmbufs` specified the number of small mbufs for the network, most often used to store network headers and small packets.  Default values are typically very generous and do not need to be overridden.
1031
1032 #### `net.inet.ip.portrange.*` 
1033
1034 The `net.inet.ip.portrange.*` sysctl variables control the port number ranges automatically bound to TCP and UDP sockets. There are three ranges: a low range, a default range, and a high range. Most network programs use the default range which is controlled by the `net.inet.ip.portrange.first` and `net.inet.ip.portrange.last`, which default to 1024 and 5000, respectively. Bound port ranges are used for outgoing connections, and it is possible to run the system out of ports under certain circumstances. This most commonly occurs when you are running a heavily loaded web proxy. The port range is not an issue when running servers which handle mainly incoming connections, such as a normal web server, or has a limited number of outgoing connections, such as a mail relay. For situations where you may run yourself out of ports, it is recommended to increase `net.inet.ip.portrange.last` modestly. A value of `10000`, `20000` or `30000` may be reasonable. You should also consider firewall effects when changing the port range. Some firewalls may block large ranges of ports (usually low-numbered ports) and expect systems to use higher ranges of ports for outgoing connections -- for this reason it is recommended that `net.inet.ip.portrange.first` be lowered.
1035
1036 #### TCP Bandwidth Delay Product 
1037
1038 The TCP Bandwidth Delay Product Limiting is similar to TCP/Vegas in NetBSD. It is enabled by default but can be disabled by setting `net.inet.tcp.inflight_enable` sysctl variable to `0`. The system will attempt to calculate the bandwidth delay product for each connection and limit the amount of data queued to the network to just the amount required to maintain optimum throughput.
1039
1040 This feature is useful if you are serving large amounts of data concurrently, such as a media server might do, particularly when the packets are constricted by a WAN, especially if you are also using window scaling or have configured a large send window.  For production use changing `net.inet.tcp.inflight_min` may be beneficial. However, note that setting high minimums may effectively disable bandwidth limiting depending on the link. The limiting feature reduces the amount of data built up in intermediate route and switch packet queues as well as reduces the amount of data built up in the local host's interface queue. With fewer packets queued up, interactive connections, especially over slow modems, will also be able to operate with lower ***Round Trip Times***. However,  this feature only effects data transmission (uploading / server side). It has no effect on data reception (downloading).
1041
1042 Adjusting `net.inet.tcp.inflight_stab` is ***not*** recommended. This parameter defaults to 50, representing 4 maximal packets added to the bandwidth delay product window calculation. The additional window is required to stabilize the algorithm and improve responsiveness to changing conditions, but it can also result in higher ping times over slow links (though still much lower than you would get without the inflight algorithm). In such cases, you may wish to try reducing this parameter to 30, 15, 10, or 5; and may also have to reduce `net.inet.tcp.inflight_min` (for example, to 3500) to get the desired effect. Reducing these parameters should be done as a last resort only.
1043
1044 ## Adding Swap Space 
1045
1046 No matter how well you plan, sometimes a system does not run as you expect. If you find you need more swap space, it is simple enough to add.  A second situation that arises is when a system has a small SSD and a large HDD where using [swapcache(8)] (http://leaf.dragonflybsd.org/cgi/web-man?command=swapcache&section=8) might be useful.
1047
1048 You have three ways to increase swap space: paging to a fast storage device, enabling swap over NFS, and creating a swap file on an existing partition.
1049
1050 ### Swap on a New Storage Device
1051
1052 The best way to add swap, of course, is to use this as an excuse to add a SSD or HDD to system. You can always use another storage device, after all. If you can do this, go reread the discussion about swap space in [configtuning-initial.html Section 6.2] for some suggestions on how to best arrange your swap.  By convention, DragonFly recommends that swap always use the 'b' partition in a disklabel to avoid accidents.
1053
1054 ### Swapping over NFS 
1055
1056 Swapping over NFS is only recommended if you do not have local storage to swap to. Even though DragonFly has an excellent NFS implementation, NFS swapping will be limited by the available network bandwidth and puts an additional burden on the NFS server.
1057
1058 Swapping on a file over NFS can be done simply via `swapon <filepath>`.  It is recommended that this command be placed in /etc/rc.local.
1059
1060 DragonFly only recommends swap on actual storage devices.  DragonFly does not recommend NFS-based swap.  If you do use NFS-based swap the swap file on the NFS server may require special configuration to prevent block reallocation by the underlying filesystem (which can destroy performance or fill up the drive).  On UFS, pre-zero the swap file.  On HAMMER2, use the `hammer2` command to disable the check code and disable compression on the file in order to disable the normal copy-on-write block reallocation operation.
1061
1062 ### Swapfiles 
1063
1064 DragonFly does NOT recommend swapping to a file.  At best you can use this technique to swap to a file over NFS, but generally speaking paging to a file can lead to system deadlocks in low-memory situations due to resources needed by the filesystem itself to execute the paging operation.  It just isn't a good idea.
1065
1066 You can create a file of a specified size to use as a swap file. In our example here we will use a 64M file called `/usr/swap0`. You can use any name you want, of course.  On a real system you will want to size the swap to at least be the same as the amount of physical ram in the machine, and as already mentioned, we do NOT recommend swapping to a file due to the deadlock risk.
1067
1068  **Example 6-1. Creating a Swapfile** 
1069
1070   1. Be certain that your kernel configuration includes the vnode driver. It is ***not*** in recent versions of `GENERIC`.
1071
1072       
1073
1074          pseudo-device   vn 1   #Vnode driver (turns a file into a device)
1075
1076   
1077
1078   1. Create a swapfile (`/usr/swap0`):  Ensure there is sufficient space on the filesystem for the swapfile.  Pre-zero the file.  On HAMMER2, also disable the check mode and compression to prevent block reallocation on write.  The following sequence is for HAMMER2.
1079
1080          # echo -n > /usr/swap0
1081          # hammer2 setcheck none /usr/swap0
1082          # hammer2 setcomp none /usr/swap0 
1083          # dd if=/dev/zero of=/usr/swap0 bs=1024k count=64
1084
1085   
1086
1087   1. Set proper permissions on (`/usr/swap0`):
1088
1089       
1090
1091          # chmod 0600 /usr/swap0
1092
1093   
1094
1095   1. Enable the swap file in `/etc/rc.conf`:
1096
1097       
1098
1099          swapfile="/usr/swap0"   # Set to name of swapfile if aux swapfile desired.
1100
1101   
1102
1103   1. Reboot the machine or to enable the swap file immediately, type:
1104
1105       
1106
1107          # vnconfig -e /dev/vn0 /usr/swap0 swap
1108
1109   
1110
1111 ## Power and Resource Management 
1112
1113 ***Written by Hiten Pandya and Tom Rhodes. ***
1114
1115 It is very important to utilize hardware resources in an efficient manner. Before ACPI was introduced, it was very difficult and inflexible for operating systems to manage the power usage and thermal properties of a system. The hardware was controlled by some sort of BIOS embedded interface, such as ***Plug and Play BIOS (PNPBIOS)***, or ***Advanced Power Management (APM)*** and so on. Power and Resource Management is one of the key components of a modern operating system. For example, you may want an operating system to monitor system limits (and possibly alert you) in case your system temperature increased unexpectedly.
1116
1117 In this section, we will provide comprehensive information about ACPI. References will be provided for further reading at the end. Please be aware that ACPI is available on DragonFly systems as a default kernel module.
1118
1119 ### What Is ACPI? 
1120
1121 Advanced Configuration and Power Interface (ACPI) is a standard written by an alliance of vendors to provide a standard interface for hardware resources and power management (hence the name). It is a key element in ***Operating System-directed configuration and Power Management***, i.e.: it provides more control and flexibility to the operating system (OS). Modern systems ***stretched*** the limits of the current Plug and Play interfaces (such as APM), prior to the introduction of ACPI. ACPI is the direct successor to APM (Advanced Power Management).  In DragonFly, ACPI is now mandatory and APM is no longer used.
1122
1123 ### Configuring ACPI 
1124
1125 The `acpi.ko` driver is now always compiled into the kernel and present by default.  Most systems simply will not operate properly without it.
1126
1127  **Note:** ACPI and APM cannot coexist and should be used separately. The last one to load will terminate if the driver notices the other running.
1128
1129 In the simplest form, ACPI can be used to put the system into a sleep mode with [acpiconf(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=acpiconf&section=8), the `-s` flag, and a `1-5` option. Most users will only need `1`. Option `5` will do a soft-off which is the same action as:
1130
1131   
1132
1133     # halt -p
1134
1135 The other options are available. Check out the [acpiconf(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=acpiconf&section=8) manual page for more information.
1136
1137 ## Using and Debugging DragonFly ACPI 
1138
1139 ***Written by Nate Lawson. With contributions from Peter Schultz and Tom Rhodes. ***
1140
1141 ACPI is a fundamentally new way of discovering devices, managing power usage, and providing standardized access to various hardware previously managed by the BIOS. Progress is being made toward ACPI working on all systems, but bugs in some motherboards ***ACPI Machine Language*** (AML) bytecode, incompleteness in DragonFly's kernel subsystems, and bugs in the Intel ACPI-CA interpreter continue to appear.
1142
1143 This document is intended to help you assist the DragonFly ACPI maintainers in identifying the root cause of problems you observe and debugging and developing a solution. Thanks for reading this and we hope we can solve your system's problems.
1144
1145 ### Submitting Debugging Information 
1146
1147  **Note:** Before submitting a problem, be sure you are running the latest BIOS version and, if available, embedded controller firmware version.
1148
1149 For those of you that want to submit a problem right away, please send the following information to [bugs](http://leaf.dragonflybsd.org/mailarchive/)
1150
1151 * Description of the buggy behavior, including system type and model and anything that causes the bug to appear. Also, please note as accurately as possible when the bug began occurring if it is new for you.
1152
1153 * The dmesg output after ***boot `-v`***, including any error messages generated by you exercising the bug.
1154
1155 * dmesg output from ***boot `-v`*** with ACPI disabled, if disabling it helps fix the problem.
1156
1157 * Output from ***sysctl hw.acpi***. This is also a good way of figuring out what features your system offers.
1158
1159 * URL where your ***ACPI Source Language*** (ASL) can be found. Do ***not*** send the ASL directly to the list as it can be very large. Generate a copy of your ASL by running this command:
1160       
1161
1162       # acpidump -t -d > name-system.asl
1163
1164   
1165
1166   (Substitute your login name for `name` and manufacturer/model for `system`. Example: `njl-FooCo6000.asl`)
1167
1168 ### Background 
1169
1170 ACPI is present in all modern computers that conform to the ia32 (x86), ia64 (Itanium), and amd64 (AMD) architectures. The full standard has many features including CPU performance management, power planes control, thermal zones, various battery systems, embedded controllers, and bus enumeration. Most systems implement less than the full standard. For instance, a desktop system usually only implements the bus enumeration parts while a laptop might have cooling and battery management support as well. Laptops also have suspend and resume, with their own associated complexity.
1171
1172 An ACPI-compliant system has various components. The BIOS and chipset vendors provide various fixed tables (e.g., FADT) in memory that specify things like the APIC map (used for SMP), config registers, and simple configuration values. Additionally, a table of bytecode (the ***Differentiated System Description Table*** DSDT) is provided that specifies a tree-like name space of devices and methods.
1173
1174 The ACPI driver must parse the fixed tables, implement an interpreter for the bytecode, and modify device drivers and the kernel to accept information from the ACPI subsystem. For DragonFly, Intel has provided an interpreter (ACPI-CA) that is shared with Linux and NetBSD®. The path to the ACPI-CA source code is `src/sys/dev/acpica5`.  Finally, drivers that implement various ACPI devices are found in `src/sys/dev/acpica5`.
1175
1176 ### Common Problems 
1177
1178 For ACPI to work correctly, all the parts have to work correctly. Here are some common problems, in order of frequency of appearance, and some possible workarounds or fixes.
1179
1180 #### Suspend/Resume 
1181
1182 ACPI has three suspend to RAM (STR) states, `S1`-`S3`, and one suspend to disk state (`STD`), called `S4`. `S5` is ***soft off*** and is the normal state your system is in when plugged in but not powered up. `S4` can actually be implemented two separate ways. `S4`BIOS is a BIOS-assisted suspend to disk. `S4`OS is implemented entirely by the operating system.
1183
1184 Start by checking `sysctl` `hw.acpi` for the suspend-related items. Here are the results for my Thinkpad:
1185
1186     hw.acpi.supported_sleep_state: S3 S4 S5
1187
1188     hw.acpi.s4bios: 0
1189
1190 This means that I can use `acpiconf -s` to test `S3`, `S4`OS, and `S5`. If `s4bios` was one (`1`), I would have `S4`BIOS support instead of `S4` OS.
1191
1192 When testing suspend/resume, start with `S1`, if supported. This state is most likely to work since it doesn't require much driver support. No one has implemented `S2` but if you have it, it's similar to `S1`. The next thing to try is `S3`. This is the deepest STR state and requires a lot of driver support to properly reinitialize your hardware. If you have problems resuming, feel free to email the [bugs](http://leaf.dragonflybsd.org/mailarchive/) list but do not expect the problem to be resolved since there are a lot of drivers/hardware that need more testing and work.
1193
1194 To help isolate the problem, remove as many drivers from your kernel as possible. If it works, you can narrow down which driver is the problem by loading drivers until it fails again. Typically binary drivers like `nvidia.ko`,  **X11**  display drivers, and USB will have the most problems while Ethernet interfaces usually work fine. If you can load/unload the drivers ok, you can automate this by putting the appropriate commands in `/etc/rc.suspend` and `/etc/rc.resume`. There is a commented-out example for unloading and loading a driver. Try setting `hw.acpi.reset_video` to zero (0) if your display is messed up after resume. Try setting longer or shorter values for `hw.acpi.sleep_delay` to see if that helps.
1195
1196 Another thing to try is load a recent Linux distribution with ACPI support and test their suspend/resume support on the same hardware. If it works on Linux, it's likely a DragonFly driver problem and narrowing down which driver causes the problems will help us fix the problem. Note that the ACPI maintainers do not usually maintain other drivers (e.g sound, ATA, etc.) so any work done on tracking down a driver problem should probably eventually be posted to the [bugs](http://leaf.dragonflybsd.org/mailarchive/) list and mailed to the driver maintainer. If you are feeling adventurous, go ahead and start putting some debugging [printf(3)](http://leaf.dragonflybsd.org/cgi/web-man?command#printf&section3)s in a problematic driver to track down where in its resume function it hangs.
1197
1198 Finally, try disabling ACPI and enabling APM instead. If suspend/resume works with APM, you may be better off sticking with APM, especially on older hardware (pre-2000). It took vendors a while to get ACPI support correct and older hardware is more likely to have BIOS problems with ACPI.
1199
1200 <-- XXX: mention sensors somewhere; but not in this section -->
1201
1202 #### System Hangs (temporary or permanent) 
1203
1204 Most system hangs are a result of lost interrupts or an interrupt storm. Chipsets have a lot of problems based on how the BIOS configures interrupts before boot, correctness of the APIC (MADT) table, and routing of the ***System Control Interrupt*** (SCI).
1205
1206 Interrupt storms can be distinguished from lost interrupts by checking the output of `vmstat -i` and looking at the line that has `acpi0`. If the counter is increasing at more than a couple per second, you have an interrupt storm. If the system appears hung, try breaking to DDB ( **CTRL** + **ALT** + **ESC**  on console) and type `show interrupts`.
1207
1208 Your best hope when dealing with interrupt problems is to get developer help via the bug reporting system or #dragonflybsd on irc.efnet.org.
1209
1210 #### Panics 
1211
1212 Panics are relatively rare for ACPI and are the top priority to be fixed. The first step is to isolate the steps to reproduce the panic (if possible) and get a backtrace. Follow the advice for enabling `options DDB` and setting up a serial console (see [ this section](serialconsole-setup.html#SERIALCONSOLE-DDB)) or setting up a [dump(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=dump&section=8) partition. You can get a backtrace in DDB with `tr`. If you have to handwrite the backtrace, be sure to at least get the lowest five (5) and top five (5) lines in the trace.
1213
1214 Then, try to isolate the problem by booting with ACPI disabled. If that works, you can isolate the ACPI subsystem by using various values of `debug.acpi.disable`. See the [acpi(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=acpi&section=4) manual page for some examples.
1215
1216 #### System Powers Up After Suspend or Shutdown 
1217
1218 First, try setting `hw.acpi.disable_on_poweroff#0` in [loader.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=loader.conf&section=5). This keeps ACPI from disabling various events during the shutdown process. Some systems need this value set to ***1*** (the default) for the same reason. This usually fixes the problem of a system powering up spontaneously after a suspend or poweroff.
1219
1220 #### Other Problems 
1221
1222 If you have other problems with ACPI (working with a docking station, devices not detected, etc.), please email a description to the mailing list as well; however, some of these issues may be related to unfinished parts of the ACPI subsystem so they might take a while to be implemented. Please be patient and prepared to test patches we may send you.
1223
1224 ### Getting Debugging Output From ACPI 
1225
1226 The ACPI driver has a very flexible debugging facility. It allows you to specify a set of subsystems as well as the level of verbosity. The subsystems you wish to debug are specified as ***layers*** and are broken down into ACPI-CA components (ACPI_ALL_COMPONENTS) and ACPI hardware support (ACPI_ALL_DRIVERS). The verbosity of debugging output is specified as the ***level*** and ranges from ACPI_LV_ERROR (just report errors) to ACPI_LV_VERBOSE (everything). The ***level*** is a bitmask so multiple options can be set at once, separated by spaces. In practice, you will want to use a serial console to log the output if it is so long it flushes the console message buffer.
1227
1228 Debugging output is not enabled by default. To enable it, add `options ACPI_DEBUG` to your kernel config and recompile your kernel. You can add `ACPI_DEBUG=1` to your `/etc/make.conf` to enable it globally.
1229
1230 Add your desired debug level and layer to `loader.conf`. This example enables debug messages for all ACPI-CA components and all ACPI hardware drivers (CPU, LID, etc.) It will only output error messages, the least verbose level.
1231
1232     
1233
1234     debug.acpi.layer="ACPI_ALL_COMPONENTS ACPI_ALL_DRIVERS"
1235
1236     debug.acpi.level="ACPI_LV_ERROR"
1237
1238 If the information you want is triggered by a specific event (say, a suspend and then resume), you can leave out changes to `loader.conf` and instead use `sysctl` to specify the layer and level after booting and preparing your system for the specific event. The `sysctl`s are named the same as the tunables in `loader.conf`.
1239
1240 ### References 
1241
1242 More information about ACPI may be found in the following locations:
1243
1244 * The [FreeBSD ACPI mailing list](http://lists.FreeBSD.org/mailman/listinfo/freebsd-acpi) (This is FreeBSD-specific; posting DragonFly questions here may not generate much of an answer.)
1245
1246 * The ACPI Mailing List Archives (FreeBSD) http://lists.freebsd.org/pipermail/freebsd-acpi/
1247
1248 * The old ACPI Mailing List Archives (FreeBSD) http://home.jp.FreeBSD.org/mail-list/acpi-jp/
1249
1250 * The ACPI 2.0 Specification http://acpi.info/spec.htm
1251
1252 * DragonFly Manual pages: [acpidump(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=acpidump&section8), [acpiconf(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=acpiconf&section=8), [acpidb(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=acpidb&section=8)
1253
1254 * [DSDT debugging resource](http://www.cpqlinux.com/acpi-howto.html#fix_broken_dsdt). (Uses Compaq as an example but generally useful.)
1255