No commit message specified.
[ikiwiki.git] / nmatavka / index.mdwn
1
2 ## Disk Slices, Partitions and local UNIX file systems 
3
4 Here we describe how disks are subdivided.
5
6 <!-- XXX: mention serno stuff -->
7
8 ### Slices 
9
10 A disk can be subdivided in slices.
11
12 Slices are named `s0`, `s1` and so on.
13
14 For example the disk `ad6` can contain the slice `ad6s3`.
15
16 DragonFly support two schemes for slices, MBR and GPT, either of them will manage all slices on a disk:
17
18 * MBR: set up using [fdisk(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=fdisk&amp;section8), can be up to 2 TB in size.  MBR slices are numbered from 1; but if disk is ***dangerously dedicated*** it has slice number 0.
19
20 * GPT: set up using [gpt(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=gpt&amp;section8), can be extremely large: size up to 8 billion TB.  DragonFly doesn't support booting from a GPT slice in DragonFly  2.0.  Note that GPT slices are numbered from 0. ***Dangerously dedicated*** is not supported nor needed for GPT.  DragonFly 2.1 does have some support for booting from a GPT slice, this is described in [gpt(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=gpt&amp;section=8).
21
22 ### Partitions 
23
24 Partitions are contained in slices.
25
26 Partitions are named `a`, `b` and so on.
27
28 DragonFly support 16 partitions per slice, that is `a` through `p`.
29
30 For example the partition `ad6s3a` is contained in the slice `ad6s3`.
31
32 Partition layout is defined in a label on the slice where the partition reside. DragonFly support two types of disk labels, disklabel32 and disklabel64 (the default):
33
34 * [disklabel32(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel&amp;section8): 32 bit disk label which can use slices with size up to 2 TB.
35
36 * [disklabel64(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel64&amp;section8): 64 bit disk label which can use very large slices: size up to 16 million TB.
37
38 ### Local UNIX file systems 
39
40 File systems are contained in partitions.  Each partition can contain only one file system, which means that file systems often are described by either their typical mount point in the file system hierarchy, or the letter of the partition they are contained in.  ***Partition*** does not have the same meaning as the common usage of the term partition (for example, MS-DOS partition), because of DragonFly's UNIX® heritage.
41
42 DragonFly support two local UNIX file systems, UFS and HAMMER:
43
44 * UFS: The classical BSD UNIX file system, see [ffs(5)](http://leaf.dragonflybsd.org/cgi/web-man?command#ffs&amp;section5), it supports size up to 2 TB.
45
46 * [HAMMER(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=HAMMER&amp;section5): A new file system, as of DragonFly 2.0, with many advanced features.  HAMMER file system support size up to 1 million TB.
47
48 ### Typical disk layout 
49
50 From the above we see the following typical disk layout scenarios:
51
52 * For booting DragonFly from a local file system UFS is recommended.  A BOOT+HAMMER setup is recommended for HAMMER use, this consists of a small UFS file system for booting, typically 512MB, and a HAMMER root file system.  The BOOT file system is mounted as /boot after boot.
53
54 * For moderate storage requirements UFS can be used; it can be setup on any partition, e.g. on the same disk slice as the boot partition.  HAMMER is an alternative, with extra features supported, like history retention.  You should evaluate if HAMMER is suitable, see note below.
55
56 * If really big storage capacity is needed UFS can't fit the need.  You should evaluate if HAMMER is suitable, see note below.  For this use HAMMER needs to be used on a GPT slice with  a [disklabel64(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel64&amp;section8) label.  In DragonFly 2.0 it has to be set up on a disk separate from the boot disk.  In  DragonFly 2.1 one disk can be used for both booting and HAMMER file system on GPT slice, as some support for booting from GPT is present, as described in [gpt(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=gpt&amp;section=8).
57
58 ### HAMMER Note 
59
60 [HAMMER(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=HAMMER&amp;section5)
61
62 is a rather new file system, under active development.
63
64 As of DragonFly 2.2.1 release HAMMER is considered production ready.  At 2.0 release it was considered to be in an early Beta state .
65
66 All major features except the mirroring are quite well tested as-of the 2.2.1 release.
67
68 You should evaluate if HAMMER is suitable for your needs.
69 <!-- XXX: mention disk and memory requirements for efficient hammer use -->
70
71 Examples of ongoing development includes:
72
73 * Making HAMMER more self managing; e.g. ability to setup policy for which history to save for how long: e.g. make snapshot every hour and prune and reblock the file system regularly.  When snapshot gets older than 1 month only keep them for every 6 hours; when older than 3 months only keep snapshot for every 24 hours, when older than 3 years only keep snapshot per month.  For now you need to set up [cron(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=cron&amp;section8) jobs for this yourself, see [hammer(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=hammer&amp;section=8).
74
75 * Multi master mirroring. For now only one mirror master is supported, but multiple mirror targets, called slaves, are already supported.
76
77 * Support for shrinking existing HAMMER file systems.  The HAMMER design is prepared for this, utility just have to be written to support it.
78 <!-- XXX: is this still accurate? Do we really want to mention it here? -->
79
80 ### HAMMER Features 
81
82 [HAMMER(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=HAMMER&amp;section5) has several advanced features not found in UFS:
83
84 * Large file systems:  Up to 1 million TB, also called 1 Exabyte is supported.
85
86 * Multiple volumes:  A HAMMER file system can span up to 256 disks, each partition part of a HAMMER file system is called a volume.  Each volume can be up to 4096 TB in size.
87
88 * Support for growing and shrinking existing HAMMER file systems: adding and removing volumes from the file system.  As of 2.4 release an existing HAMMER file system can be expanded by adding extra space, see the `expand` directive to [hammer(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=hammer&amp;section=8).  The HAMMER design is also prepared for removing volumes, utilities just have to be written to support it.
89
90 * Instant crash recovery:  If a crash should occur, then HAMMER file systems will be ready a few seconds after boot, no lenghty fsck have to be run.
91
92 * Full history retention:  All file system changes are saved every ~30 seconds.  Changes are written at least when sync() is called, see [syncer(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=syncer&amp;section4).  Every time data for files are written to disk a transaction is completed, this is assigned an ID and the file updated can after this be accessed with the contents from this moment.  To access the file with the state of this moment, the transaction ID, TID for brevity, just needs to be added to the file name, like: 'file@@<TID>'.  The TID can be saved from the 'snapshot', 'cleanup', or 'synctid' [hammer(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=hammer&amp;section=8) command or looked up with the 'hammer history file' command.  This history will typically grow over time, so any disk will fill up over time.  Two things are done so disks doesn't fill up: first: big disks are used, at least 50GB is typical for HAMMER file systems, and second: unused history information is deleted regularly. Here we need to define what unused means: a TID is used if a snapshot have been taken on it. Data assigned to unused history can be reclaimed using the `prune` and `reblock` [hammer(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=hammer&amp;section=8) commands, this will also defragment the file system and can be done while the file system is in normal operation.  Generally after file system is pruned only TIDs for the snapshots or newer than newest shapshot should be used, see explanation [here](http://leaf.dragonflybsd.org/mailarchive/bugs/2008-07/msg00213.html) (more info on HAMMER design [here](http://leaf.dragonflybsd.org/mailarchive/kernel/2008-07/msg00114.html)).  See also [hammer(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=hammer&amp;section=5). 
93
94 * Mirroring:  A master file system can be mirrored online to a number of slave file systems.  Mirror targets are read-only, but does have history available.  History retension policy can even be different on slaves and master.  Mirroring can be over network and unreliable connections are handled gracefully.
95
96 * Data integrity:  HAMMER has high focus in data integrity and implements a CRC checksum on all data, this means that if disk fails with bit errors it will be detected.
97
98 More info on HAMMER can be found [here](http://www.dragonflybsd.org/hammer/index.html).
99
100 DragonFly also uses disk space for ***swap space***.  Swap space provides DragonFly with ***virtual memory***.  This allows your computer to behave as though it has much more memory than it actually does.  When DragonFly runs low on memory it moves some of the data that is not currently being used to the swap space, and moves it back in (moving something else out) when it needs it.
101
102 <!-- XXX: mention swapcache, and also how to configure and use it (somewhere else, probably) -->
103
104 ### Adding a Disk 
105
106 Adding a disk is done by installing it physically, and to connect it to a disk controller that DragonFly supports.  If you are in doubt if controller is supported, manual pages for disk controllers can be consulted ('man -k disk' or 'man -k scsi' can be of help).  The easiest thing is normally to boot DargonFly with the controller installed and note if boot message contains the controller.
107
108 Assuming that disk `ad6` is installed, we could set it up using [fdisk(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=fdisk&amp;section8) and  disklabel(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel&amp;section8) or  [gpt(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=gpt&amp;section8) and 
109 [disklabel64(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel64&amp;section8).
110
111 In this example we choose [gpt(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=gpt&amp;section=8) & [disklabel64(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel64&amp;section=8).
112
113 <!-- XXX: mention that disklabel64 is default now -->
114     
115
116     # gpt -v create ad6
117
118     ...
119
120     # gpt add -s1 ad6
121
122     ad6s0
123
124     # gpt add ad6
125
126     ad6s1
127
128     # gpt show ad6
129
130     ...
131
132 Here we first create the GPT and then add two slices.  In this example the first slice added is `ad6s0`, which is made a dummy slice of size 1 sector, this is just for not having to make further reference to it, as many users remembers that `s0` has special meaning, which really isn't true for GPT slices.  The second slice is `ad6s1` which will cover the rest of the disk.
133
134     
135
136     # disklabel64 -rw ad6s1 auto
137
138     # disklabel64 -e ad6s1          # edit label to add partitions as needed
139
140 ### disklabel 
141 <!-- XXX: what is all this fuzz about dangerously dedicated? -->
142
143 For [disklabel(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel&amp;section8) labels some partitions have certain conventions associated with them.
144
145 [[!table  data="""
146 <tablestyle="width:100%"> Partition | Convention 
147 <tablestyle="width:100%"> `a` | Normally contains the root file system 
148  `b` | Normally contains swap space 
149  `c` | Normally the same size as the enclosing slice.  This allows utilities that need to work on the entire slice (for example, a bad block scanner) to work on the `c` partition. You would not normally create a file system on this partition. This is not necessarily true; it is possible to use the 'c' partition as a normal partition.
150  `d` | Partition `d` used to have a special meaning associated with it, although that is now gone.  To this day, some tools may operate oddly if told to work on partition `d`. |
151
152 """]]
153
154 Each partition-that-contains-a-file-system is stored in what DragonFly calls a ***slice***.  Slice is DragonFly's term for what the common call partitions, and again, this is because of DragonFly's UNIX background.  Slices are numbered, starting at 1.
155
156 Slice numbers follow the device name, prefixed with an `s`, starting at 1. So ***da0s1*** is the first slice on the first SCSI drive. There can only be four physical slices on a disk, but you can have logical slices inside physical slices of the appropriate type.  These extended slices are numbered starting at 5, so ***ad0s5*** is the first extended slice on the first IDE disk. These devices are used by file systems that expect to occupy a slice.
157
158 <!-- XXX: gpt allows for way more than 4 partitions... let's remove this stuff above -->
159
160 ***Dangerously dedicated*** physical drives are accessed as slice 0.
161
162 Slices, ***dangerously dedicated*** physical drives, and other drives contain ***partitions***, which are represented as letters from `a` to `p`.  This letter is appended to the device name, so ***da0s0a*** is the a partition on the first da drive, which is ***dangerously dedicated***. ***ad1s3e*** is the fifth partition in the third slice of the second IDE disk drive.
163
164 Finally, each disk on the system is identified.  A disk name starts with a code that indicates the type of disk, and then a number, indicating which disk it is.  Disk numbering starts at 0. Common codes that you will see are listed in [Table 3-1](disk-organization.html#BASICS-DEV-CODES).
165
166 <!-- XXX: here would probably be the right place to talk about serno -->
167
168 When referring to a partition DragonFly requires that you also name the slice and disk that contains the partition, and when referring to a slice you should also refer to the disk name. Do this by listing the disk name, `s`, the slice number, and then the partition letter.  Examples are shown in [Example 3-1](disk-organization.html#BASICS-DISK-SLICE-PART).
169
170 <!-- XXX: later talk also about devfs, definitely not here though. also, devfs rules -->
171
172 [Example 3-2](disk-organization.html#BASICS-CONCEPT-DISK-MODEL) shows a conceptual model of the disk layout that should help make things clearer.
173
174 In order to install DragonFly you must first configure the disk slices, then create partitions within the slice you will use for DragonFly, and then create a file system (or swap space) in each partition, and decide where that file system will be mounted.
175
176 ***'Table 3-1. Disk Device Codes***'
177
178 [[!table  data="""
179 <tablestyle="width:100%"> Code | Meaning 
180 <tablestyle="width:100%"> `ad` | ATAPI (IDE) disk 
181  `da` | SCSI direct access disk 
182  `acd` | ATAPI (IDE) CDROM 
183  `cd` | SCSI CDROM 
184  `vn` | Virtual disk
185  `fd` | Floppy disk |
186
187 """]]
188
189 ***'Example 3-1. Sample Disk, Slice, and Partition Names***'
190
191 [[!table  data="""
192 <tablestyle="width:100%"> Name | Meaning 
193 <tablestyle="width:100%"> `ad0s1a` | The first partition (`a`) on the first slice (`s1`) on the first IDE disk (`ad0`). 
194  `da1s2e` | The fifth partition (`e`) on the second slice (`s2`) on the second SCSI disk (`da1`). |
195
196 """]]
197
198 ***'Example 3-2. Conceptual Model of a Disk***'
199
200 This diagram shows DragonFly's view of the first IDE disk attached to the system. Assume that the disk is 4 GB in size, and contains two 2 GB slices (MS-DOS partitions).  The first slice contains a MS-DOS disk, `C:`, and the second slice contains a DragonFly installation. This example DragonFly installation has three partitions, and a swap partition.
201
202 The three partitions will each hold a file system. Partition `a` will be used for the root file system, `e` for the `/var` directory hierarchy, and `f` for the `/usr` directory hierarchy.
203
204 <!-- XXX: image -->
205
206 ## Mounting and Unmounting File Systems 
207
208 The file system is best visualized as a tree, rooted at `/`.
209
210 The directories, e.g. `/dev` and `/usr`, in the root directory are branches,
211
212 which may have their own branches, such as `/usr/local`, and so on.
213
214 There are various reasons to house some of these directories on separate file systems. `/var` contains the directories `log/` and `spool/`, and various types of temporary files, and as such, may get filled up. Filling up the root file system is not a good idea, so splitting `/var` from `/` is often favorable.
215
216 Another common reason to contain certain directory trees on other file systems is if they are to be housed on separate physical disks, e.g. CD-ROM, or are used as separate virtual disks, such as [Network File System](network-nfs.html) exports.
217
218 ### The fstab File 
219
220 During the [boot process](boot.html), file systems listed in `/etc/fstab` are automatically mounted (unless they are listed with the `noauto` option).
221
222 The `/etc/fstab` file contains a list of lines of the following format:
223   
224
225     device       mount-point   fstype     options      dumpfreq     passno
226
227 These parameters have the following meaning:
228
229 * `device`: A device name (which should exist), as explained [here](disks-naming.html).
230
231 * `mount-point`: A directory (which should exist), on which to mount the file system.
232
233 * `fstype`: The file system type to pass to [mount(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=mount&section8). The default DragonFly file system is `ufs`.
234
235 * `options`: Either `rw` for read-write file systems, or `ro` for read-only file systems, followed by any other options that may be needed. A common option is `noauto` for file systems not normally mounted during the boot sequence. Other options are listed in the [mount(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=mount&section8) manual page.
236
237 * `dumpfreq`: This is used by [dump(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=dump&section8) to determine which file systems require dumping. If the field is missing, a value of zero is assumed.
238
239 * `passno`: This determines the order in which file systems should be checked. File systems that should be skipped should have their `passno` set to zero. The root file system (which needs to be checked before everything else) should have its `passno` set to one, and other file systems' `passno` should be set to values greater than one. If more than one file systems have the same `passno` then [fsck(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=fsck&section8) will attempt to check file systems in parallel if possible.
240
241 Consult the [fstab(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=fstab&section5) manual page for more information on the format of the `/etc/fstab` file and the options it contains.
242
243 ### The mount Command 
244
245 The [mount(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=mount&section8) command is what is ultimately used to mount file systems.
246
247 In its most basic form, you use:
248
249     
250
251     # mount device mountpoint
252
253 Or, if `mountpoint` is specified in `/etc/fstab`, just:
254
255     
256
257     # mount mountpoint
258
259 There are plenty of options, as mentioned in the [mount(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=mount&section8) manual page, but the most common are:
260
261  **Mount Options** 
262
263 * `-a`: Mount all the file systems listed in `/etc/fstab`. Except those marked as `noauto`, excluded by the `-t` flag, or those that are already mounted.
264
265 * `-d`: Do everything except for the actual mount system call. This option is useful in conjunction with the `-v` flag to determine what [mount(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=mount&section8) is actually trying to do.
266
267 * `-f`: Force the mount of an unclean file system (dangerous), or forces the revocation of write access when downgrading a file system's mount status from read-write to read-only.
268
269 * `-r`: Mount the file system read-only. This is identical to using the `rdonly` argument to the `-o` option.
270
271 * `-t` ***fstype***: Mount the given file system as the given file system type, or, if used with `-a` option, mount only file systems of the given type. `ufs` is the default file system type.
272
273 * `-u`: Update mount options on the file system.
274
275 * `-v`: Be verbose.
276
277 * `-w`: Mount the file system read-write.
278
279 The `-o` option takes a comma-separated list of the options, including the following:
280
281 * `nodev:` Do not interpret special devices on the file system. This is a useful security option.
282
283 * `noexec`: Do not allow execution of binaries on this file system. This is also a useful security option.
284
285 * `nosuid`: Do not interpret setuid or setgid flags on the file system. This is also a useful security option.
286
287 ### The umount Command 
288
289 The [umount(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=umount&section8) command takes, as a parameter, one of a mountpoint, a device name, or the `-a` or `-A` option.
290
291 All forms take `-f` to force unmounting, and `-v` for verbosity. Be warned that `-f` is not generally a good idea. Forcibly unmounting file systems might crash the computer or damage data on the file system.
292
293 `-a` and `-A` are used to unmount all mounted file systems, possibly modified by the file system types listed after `-t`. `-A`, however, does not attempt to unmount the root file system.
294
295
296
297
298 ================
299 [[!toc  levels=6]]
300
301 # Chapter 1 Introduction 
302
303 ***Restructured, reorganized, and parts rewritten by Jim Mock. ***
304
305 ## Synopsis 
306
307 Thank you for your interest in DragonFly! The following chapter covers various aspects of the DragonFly Project, such as its history, goals, development model, and so on.
308
309 After reading this chapter, you will know:
310
311 * how DragonFly relates to other computer operating systems;
312
313 * the history of the DragonFly Project;
314
315 * the goals of the DragonFly Project;
316
317 * the basics of the DragonFly open-source development model; and of course:
318
319 * where the name ***DragonFly*** comes from.
320
321 ----
322
323 ## Welcome to DragonFly! 
324
325 DragonFly is a [[4.4BSD-Lite|http://en.wikipedia.org/wiki/Berkeley_Software_Distribution]] unix operating system for Intel (x86) and amd64 (x86_64) architectures.
326
327 ### What Can DragonFly Do? 
328
329 <!-- Cutout of "features". This is outdated bullshit -->
330
331 Work on BSD-flavor Unix systems running on PC compatible hardware started as a fork of the 4.4BSD-Lite release from Computer Systems Research Group (CSRG) at the University of California at Berkeley.  One of the variants that became quite popular became known later as FreeBSD.  DragonFly BSD started out as a fork and continuation of FreeBSD 4.8. 
332
333 Like all other modern PC-compatible BSD variants, it carries on the distinguished tradition of BSD systems development. In addition to the fine work provided by CSRG, the DragonFly Project has put in many thousands of hours in fine-tuning the system for maximum performance and reliability in real-life load situations. 
334
335 As many of the commercial giants struggle to field PC operating systems with such features, performance and reliability, DragonFly can offer them ***now***!
336
337 For example the `Hammer` filesystem, the default in DragonFly BSD, is the most powerful and reliable filesystem available on any operating system.
338
339 The applications to which DragonFly can be put are truly limited only by your own imagination. From software development to factory automation, inventory control to azimuth correction of remote satellite antennae; if it can be done with a commercial UNIX product, it is more than likely that you can do it with DragonFly, too! DragonFly also benefits significantly from literally thousands of high-quality applications developed by research centres and universities around the world, often available at little to no cost. Commercial applications are also available and appearing in greater numbers every day.
340
341 Because the source code for DragonFly itself is generally available, the system can also be customized to an almost unheard-of degree for special applications or projects, and in ways not generally possible with operating systems from most major commercial vendors. Here is just a sampling of some of the applications in which people are currently using DragonFly:
342
343 The robust TCP/IP networking built into DragonFly renders it an ideal platform for a variety of Internet services such as:
344
345 * FTP servers
346
347 * World Wide Web servers (standard or secure [SSL])
348
349 * Firewalls and NAT (***IP masquerading***) gateways
350
351 * Electronic Mail servers
352
353 * USENET News or Bulletin Board Systems
354
355 * And more...
356
357 With DragonFly, you can install on almost any PC, from older 32 bit computers running 386 or Pentium chips, to modern 64 bit Intel Core or AMD X64 desktop CPUs, and even up to and including high end Xeon CPUs.  All of these CPUs share a common ancestry and instruction set, going back to the original Intel 80386 CPU, the first fully 32-bit desktop CPU for "IBM PC compatible" computers.
358
359 Here are some of the fields where people are using Dragonfly BSD, and the reasons that they find that DragonFly BSD fits their needs:
360
361 * ***Education:*** Are you a student of computer science or a related engineering field? There is no better way of learning about operating systems, computer architecture, and networking than the hands-on, under-the-hood experience that DragonFly can provide. A number of freely available CAD, mathematical, and graphic design packages also make it highly useful to those whose primary interest in a computer is to get ***other*** work done!
362
363 * ***Research:*** With source code for the entire system available, DragonFly is an excellent platform for research in operating systems as well as other branches of computer science. DragonFly's freely available nature also makes it possible for remote groups to collaborate on ideas or shared development without having to worry about special licensing agreements or limitations on what may be discussed in open forums.
364
365 * ***Networking:*** Need a new router? A name server (DNS)? A firewall to keep people out of your internal network? DragonFly can easily turn that unused older PC sitting in the corner into an advanced router with sophisticated packet-filtering capabilities.
366
367 * ***X Window workstation:*** DragonFly is a fine choice for an inexpensive X terminal solution, using the freely available X.org server. Unlike an X terminal, DragonFly allows many applications to be run locally if desired, thus relieving the burden on a central server. DragonFly can even boot ***diskless***, making individual workstations even cheaper and easier to administer.
368
369 * ***Software Development:*** The basic DragonFly system comes with a full complement of development tools including the renowned GNU C/C++ compiler and debugger.
370
371 DragonFly is available via anonymous FTP or GIT. Please see [Appendix A](mirrors.html) for more information about obtaining DragonFly.
372
373 For more help on installing, see the appropriate sections of this handbook.
374
375 ----
376
377 ## About the DragonFly Project 
378
379 The following section provides some background information on the project, including a brief history, project goals, and the development model of the project.
380
381 ### A Brief History of DragonFly 
382
383 Matthew Dillon, one of the developers for FreeBSD, was growing increasingly frustrated with the FreeBSD Project's direction for release 5. The FreeBSD 5 release had been delayed multiple times, and had performance problems compared to earlier releases of FreeBSD.  DragonFly was announced in June of 2003. The code base was taken from the 4.8 release of FreeBSD, which offered better performance and more complete features. Development has proceeded at a very quick rate since then, with Matt Dillon and a group of developers fixing longstanding BSD bugs and modernizing the new DragonFly system.
384
385 ### DragonFly Project Goals 
386
387 DragonFly is an effort to maintain the traditional BSD format -- lean, stable code -- along with modern features such as lightweight threads, a workable packaging system, and a revised VFS. Underpinning all this work is efficient support for multiple processors, something rare among open source systems. Because DragonFly is built on an existing very stable code base, it is possible to make these radical changes as part of an incremental process.
388
389 ### The DragonFly Development Model 
390
391 ***Written by Justin Sherrill. ***
392
393 DragonFly is developed by many people around the world. There is no qualification process; anyone may submit his or her code, documentation, or designs, for use in the Project. Here is a general description of the Project's organizational structure.
394
395 Source for DragonFly is kept in [git](http://www.git.org/), available with each DragonFly install. The primary [git repository](http://gitweb.dragonflybsd.org/?p=dragonfly.git;a=summary) resides on a machine in California, USA. Documentation on obtaining the DragonFly source is available elsewhere in this book. The best way of getting changes made to the DragonFly source is to mail the [submit](http://www.dragonflybsd.org/mailinglists/) mailing list. Including desired source code changes (unified diff format is best) is the most useful format. A certain number of developers have access to commit changes to the DragonFly source, and can do so after review on that list. The DragonFly development model is loose; changes to the code are generally peer-reviewed and added when any objections have been corrected. There is no formal entry/rejection process, though final say on all code submissions goes to Matt Dillon, as originator of this project.
396
397 ### The Current DragonFly Release 
398
399 DragonFly is a freely available, full source 4.4BSD-Lite based release for almost all Intel and AMD based computer systems. It is based primarily on FreeBSD 4.8, and includes enhancements from U.C. Berkeley's CSRG group, NetBSD, OpenBSD, 386BSD, and the Free Software Foundation. A number of additional documents which you may find very helpful in the process of installing and using DragonFly may now also be found in the `/usr/share/doc` directory on any machine.
400
401 ### DragonFly Origin 
402 Matthew Dillon happened to take a picture of a dragonfly in his garden while trying to come up with a name for this new branch of BSD. Taking this as inspiration, "DragonFly" became the new name.
403
404 ## Updating the System 
405
406 ### Supported methods
407
408 The only **supported** method of upgrading DragonFly BSD is by building from source code. The supported upgrade process includes going from the *previous release* to *latest release*.
409
410 ### Getting the source code
411
412 There is a Makefile in /usr which will ease the task of retrieving the source tree; it needs to be run as root:
413
414     % cd /usr
415     % make src-create
416      [...]
417
418 This will check out (download) the source tree to `/usr/src` and switch to the master branch. For the stable branch, you need to check it out with the following command (remember to replace the *DragonFly_RELEASE_3_0* with the appropriate branch name for the release needed).
419
420     % cd /usr/src
421     % git checkout DragonFly_RELEASE_3_0
422
423 To see the available remote branches:
424
425     # cd /usr/src 
426     # git pull
427     # git branch -r
428
429 The leading edge (development trunk) version of the system will be the "master".
430
431 ### Build and upgrade process
432
433 The build process requires some time to build all the userland programs and the DragonFly BSD kernel. Once built, the next step is to install everything and make the upgrade target. No configuration files in */etc* are changed by this process. More details can be found in **[build(7)](http://leaf.dragonflybsd.org/cgi/web-man?command=build&section=ANY)** manpage. 
434
435     % cd /usr/src
436     % make buildworld
437     % make buildkernel
438     % make installkernel
439     % make installworld
440     % make upgrade
441     (reboot)
442
443 **Note:** You may use a concurrent build if you have a SMP (a machine with several cores or CPUs). You may specify *-j x* parameter to make where x is the number of CPUs + 1.  If you run DragonFly 2.12 or higher the kernel will auto-detect the number of CPUs your computer has and activate them all if possible. To find out how many CPUs your computer has:
444
445     % sysctl hw.ncpu
446     hw.ncpu: 2
447
448 An explanation of each step follows.
449
450 * <u>*make buildworld*</u> : This command builds all userland programs; it is the most time-consuming step of the process.  Some programs may be discarded from the build process.  For more information, see **[make.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=make.conf&section=ANY)** manpage. 
451
452 * <u>*make buildkernel*</u> : This builds the kernell by default, it uses the config file for your architecture. You may also specify a different kernel configuration file using `KERNCONF=<configfile>`. For more information, see **[make.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=make.conf&section=ANY)** manpage.
453
454 * <u>*make installkernel*</u> This installs the kernel using the config file for your architecture; again, `KERNCONF=<configfile>` can be used to specify which one to install.
455
456 * <u>*make installworld*</u> : This copies all the files built in the buildworld step (i.e. everything that is not the kernel) to their proper places in the file system.
457
458 * <u>*make upgrade*</u> : This cleans out any files made unnecessary by this upgrade.
459
460 * (reboot) : Reboot the computer to load the new kernel and use the new files installed as part of this process.
461
462 If your computer fails to boot the new kernel, you can always select 'Boot DragonFly using kernel.old' in the loader menu, so that the old kernel is loaded instead of the new one.
463
464 Additional upgrading instructions can be found in */usr/src/UPDATING* in the source tree. They can also be found online, **[here](http://gitweb.dragonflybsd.org/dragonfly.git/blob_plain/master:/UPDATING)**
465
466 # DragonFly BSD Quick Start
467
468 This QuickStart is part of the [[NewHandbook|/docs/newhandbook/]].
469
470 This document describes the DragonFly environment one will find on a newly installed system.  While you are getting started, please pay careful attention to the version or level of DragonFly that the documentation was written for.  Some documentation on this site may be out of date. Watch for the marker `(obsolete)` on items that are out of date or need updating.
471
472
473 ## Some Unix and BSD Fundamentals
474
475 If you have used another Unix flavour, another BSD, or Linux before, you may need to spend some time learning the differences between DragonFly and the system you are experienced in.  If you have never used any flavor of Unix, BSD or otherwise, and have only used Windows before, please be prepared for a lengthy period of learning.
476
477 If you already know your way around a Unix filesystem, and already know what the `/etc` folder is, how to use `vi` or `vim` to edit a file, how to use a shell like `tcsh` or `bash`, how to configure that shell, or change what shell you're using, how `su` and `sudo` work, and what a `root` account is, the rest of this page may be enough to orient you to your surroundings.
478
479 You should understand everything in the [[Unix Basics|/docs/newhandbook/UnixBasics/]] section before you proceed with trying to use your new system.
480
481 ## Disk layout of a New Dragonfly BSD System using the HAMMER filesystem
482
483 If you chose to install on the HAMMER file system during installation you will be left with a system with the following disk configuration:
484
485     # df -h
486     Filesystem                Size   Used  Avail Capacity  Mounted on
487     ROOT                      288G    12G   276G     4%    /
488     devfs                     1.0K   1.0K     0B   100%    /dev
489     /dev/serno/9VMBWDM1.s1a   756M   138M   558M    20%    /boot
490     /pfs/@@-1:00001           288G    12G   276G     4%    /var
491     /pfs/@@-1:00002           288G    12G   276G     4%    /tmp
492     /pfs/@@-1:00003           288G    12G   276G     4%    /usr
493     /pfs/@@-1:00004           288G    12G   276G     4%    /home
494     /pfs/@@-1:00005           288G    12G   276G     4%    /usr/obj
495     /pfs/@@-1:00006           288G    12G   276G     4%    /var/crash
496     /pfs/@@-1:00007           288G    12G   276G     4%    /var/tmp
497     procfs                    4.0K   4.0K     0B   100%    /proc
498
499 In this example
500
501 * `/dev/serno/9VMBWDM1` is the hard disk specified with serial number,
502 * `/dev/serno/9VMBWDM1.s1` is the first slice on the hard disk.
503
504 The disk label looks as follows:
505
506     # disklabel /dev/serno/9VMBWDM1.s1
507
508     # /dev/serno/9VMBWDM1.s1:
509     #
510     # Informational fields calculated from the above
511     # All byte equivalent offsets must be aligned
512     #
513     # boot space:    1044992 bytes
514     # data space:  312567643 blocks # 305241.84 MB (320069266944 bytes)
515     #
516     # NOTE: If the partition data base looks odd it may be
517     #       physically aligned instead of slice-aligned
518     #
519     diskid: e67030af-d2af-11df-b588-01138fad54f5
520     label:
521     boot2 data base:      0x000000001000
522     partitions data base: 0x000000100200
523     partitions data stop: 0x004a85ad7000
524     backup label:         0x004a85ad7000
525     total size:           0x004a85ad8200    # 305242.84 MB
526     alignment: 4096
527     display block size: 1024        # for partition display only
528
529     16 partitions:
530     #          size     offset    fstype   fsuuid
531       a:     786432          0    4.2BSD    #     768.000MB
532       b:    8388608     786432      swap    #    8192.000MB
533       d:  303392600    9175040    HAMMER    #  296281.836MB
534       a-stor_uuid: eb1c8aac-d2af-11df-b588-01138fad54f5
535       b-stor_uuid: eb1c8aec-d2af-11df-b588-01138fad54f5
536       d-stor_uuid: eb1c8b21-d2af-11df-b588-01138fad54f5
537
538
539 The slice has 3 partitions:
540
541 * `a` - for `/boot`
542 * `b` - for swap
543 * `d` - for `/`, a HAMMER file system labeled ROOT
544
545 When you create a HAMMER file system, you must give it a label.  Here, the installer labelled it as "ROOT" and mounted it as
546
547     ROOT                      288G    12G   276G     4%    /
548
549 A PFS is a Pseudo File System inside a HAMMER file system. The HAMMER file system in which the PFSes are created is referred to as the root file system. You should not confuse the "root" file system with the label "ROOT": the label can be anything. The installer labeled it as ROOT because it is mounted at `/`.
550
551 Now inside the root HAMMER file system you find the installer created 7 PFSes from the `df -h` output above, let us see how they are mounted in `/etc/fstab`:
552
553     # cat /etc/fstab
554
555     # Device                Mountpoint      FStype  Options         Dump    Pass#
556     /dev/serno/9VMBWDM1.s1a         /boot           ufs     rw      1       1
557     /dev/serno/9VMBWDM1.s1b         none            swap    sw      0       0
558     /dev/serno/9VMBWDM1.s1d         /               hammer  rw      1       1
559     /pfs/var                /var            null    rw              0       0
560     /pfs/tmp                /tmp            null    rw              0       0
561     /pfs/usr                /usr            null    rw              0       0
562     /pfs/home               /home           null    rw              0       0
563     /pfs/usr.obj    /usr/obj                null    rw              0       0
564     /pfs/var.crash  /var/crash              null    rw              0       0
565     /pfs/var.tmp    /var/tmp                null    rw              0       0
566     proc                    /proc           procfs  rw              0       0
567
568
569 The PFSes are mounted using a NULL mount because they are also HAMMER file systems. You can read more on NULL mounts at the [mount_null(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=mount_null&section=8) manpage.
570
571 You don't need to specify a size for the PFSes like you do for logical volumes inside a volume group for LVM. All the free space in the root HAMMER file system is available to all the PFSes; it can be seen in the `df -h` output above that the free space is the same for all PFSes and the root HAMMER file system.
572
573 If you look in `/var`
574
575     # cd /var/
576     # ls
577     account   backups   caps   cron    empty   log   msgs   run   spool   yp  at        
578     cache     crash     db     games   lib     mail  preserve   rwho  tmp
579
580 you will find the above directories.
581
582 If you look at the status of one of the PFSes, e.g. `/usr` you will see `/var/hammer` is the default snapshot directory.
583
584     # hammer pfs-status /usr/
585     /usr/   PFS #3 {
586         sync-beg-tid=0x0000000000000001
587         sync-end-tid=0x0000000117ac6270
588         shared-uuid=f33e318e-d2af-11df-b588-01138fad54f5
589         unique-uuid=f33e31cb-d2af-11df-b588-01138fad54f5
590         label=""
591         prune-min=00:00:00
592         operating as a MASTER
593         snapshots directory defaults to /var/hammer/<pfs>
594     }
595
596 At installation time, it will be seen that there is no "hammer" directory in `/var`. The reason for this is that no snapshots have yet been taken. You can verify this by checking the snapshots available for `/usr`
597
598     # hammer snapls /usr
599     Snapshots on /usr       PFS #3
600     Transaction ID          Timestamp               Note
601
602 Snapshots will appear automatically each night as the system performs housekeeping on the Hammer filesystem.  For a new volume, an immediate snapshot can be taken by running the command 'hammer cleanup'.  Among other activities, it will take a snapshot of the filesystem.
603
604     # sudo hammer cleanup
605     cleanup /                    - HAMMER UPGRADE: Creating snapshots
606             Creating snapshots in /var/hammer/root
607      handle PFS #0 using /var/hammer/root
608                snapshots - run
609                    prune - run
610                rebalance - run..
611                  reblock - run....
612                   recopy - run....
613     cleanup /var                 - HAMMER UPGRADE: Creating snapshots
614     [...]
615     cleanup /tmp                 - HAMMER UPGRADE: Creating snapshots
616     [...]
617     cleanup /usr                 - HAMMER UPGRADE: Creating snapshots
618     [...]
619     cleanup /home                - HAMMER UPGRADE: Creating snapshots
620     [...]
621     cleanup /usr/obj             - HAMMER UPGRADE: Creating snapshots
622     [...]
623     cleanup /var/crash           - HAMMER UPGRADE: Creating snapshots
624     [...]
625     cleanup /var/tmp             - HAMMER UPGRADE: Creating snapshots
626     [...]
627     cleanup /var/isos            - HAMMER UPGRADE: Creating snapshots
628     [...]
629
630 No snapshots were taken for `/tmp`, `/usr/obj` and `/var/tmp`. This is because the PFSes are flagged as `nohistory`. HAMMER tracks history for all files in a PFS.  Naturally, this consumes disk space until  history is pruned, at which point the available disk space will stabilise. To prevent temporary files on the mentioned PFSes (e.g., object files, crash dumps) from consuming disk space, the PFSes are marked as `nohistory`.
631
632 After performing nightly housekeeping, a new directory called *hammer* will be found in `/var` with the following sub directories:
633
634     # cd hammer/
635     # ls -l
636     total 0
637     drwxr-xr-x  1 root  wheel  0 Oct 13 11:51 home
638     drwxr-xr-x  1 root  wheel  0 Oct 13 11:42 root
639     drwxr-xr-x  1 root  wheel  0 Oct 13 11:43 tmp
640     drwxr-xr-x  1 root  wheel  0 Oct 13 11:51 usr
641     drwxr-xr-x  1 root  wheel  0 Oct 13 11:54 var
642
643
644 Looking inside `/var/hammer/usr`, one finds:
645
646     # cd usr/
647     # ls -l
648     total 0
649     drwxr-xr-x  1 root  wheel   0 Oct 13 11:54 obj
650     lrwxr-xr-x  1 root  wheel  25 Oct 13 11:43 snap-20101013-1143 -> /usr/@@0x0000000117ac6cb0
651
652
653 We have a symlink pointing to the snapshot transaction ID shown below.
654
655     # hammer snapls /usr
656     Snapshots on /usr       PFS #3
657     Transaction ID          Timestamp               Note
658     0x0000000117ac6cb0      2010-10-13 11:43:04 IST -
659     #
660
661 You can read more about snapshots, prune, reblance, reblock, recopy etc from [hammer(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=hammer&section=8).  Make especially sure to look under the heading "cleanup [filesystem ...]".
662
663 You can learn more about PFS mirroring [here](http://www.dragonflybsd.org/docs/how_to_implement_hammer_pseudo_file_system__40___pfs___41___slave_mirroring_from_pfs_master/)
664
665 In order to correctly map hard disk sernos to device names you can use the 'devattr' command.
666
667     # udevd
668     # devattr -d "ad*" -p serno
669     Device ad4:
670             serno = Z2AD9WN4
671     Device ad4s1:
672     Device ad4s1d:
673
674     Device ad5:
675             serno = 9VMRFDSY
676     Device ad5s1:
677     Device ad5s1d:
678
679     Device ad3:
680             serno = Z2AD9WLW
681     Device ad3s1:
682     Device ad3s1a:
683     Device ad3s1b:
684     Device ad3s1d:
685
686 Or if your disks are 'da', just change it as appropiate.
687
688 ## Configuring and Starting the SSH Server
689
690 Described in detail [[here|/docs/newhandbook/sshserver/]]
691
692 ## Software/Programs and Configuration Files Location 
693
694 DragonFly default installation contains the base software/programs from the DragonFly project itself and additional software from other sources. 
695
696 The base system binary software programs are located in the folders 
697
698     /bin    /sbin
699     /usr/bin   /usr/sbin
700
701 The configuration files for the base system can be found in `/etc`. Third-party programs use `/usr/local/etc`.
702
703 There are several different ways to install software and which version you use depends on which DragonFly BSD version you have.  You can compile things from source code, or you can use binary packages.
704
705 ## Installing Third-party Software
706
707 For an in-depth description about dealing with packaging systems, see the [[dports howto|/docs/howtos/HowToDPorts/]] . Note that although DragonFly BSD has several older package managers (like `pkgin`), as of 2014 the most modern binary package installation system is `pkg`.
708
709 ### Using pkg
710
711 Read [[dports howto|/docs/howtos/HowToDPorts/]] then for some errata, read [[this|http://lists.dragonflybsd.org/pipermail/users/2013-November/090339.html]].
712
713 You can look at the help and the man page for the pkg tool like this:
714
715 `pkg help install`
716
717 Example: Read man page for pkg-install
718
719 `man pkg-install`
720
721 ### Installing an X.org desktop X11 environment and XFCE desktop
722
723 If it's already on your system run X by typing `startx`. If it's not, be sure to check your dports configuration is finished, then install it using `pkg install xorg-7.7 xfce4-desktop`. This will install the core X.org X11 server, and an XFCE based desktop environment.
724
725 `(obsolete)`
726 Slightly out of date instructions on installing a GUI (X desktop) environment  are in the [new handbook](http://www.dragonflybsd.org/docs/newhandbook/X/).
727
728 # UNIX Basics 
729
730 ***Rewritten by Chris Shumway. ***
731
732
733 ## Synopsis 
734
735 The following chapter will cover the basic commands and functionality of the DragonFly operating system. Much of this material is relevant for any UNIX®-like operating system. Feel free to skim over this chapter if you are familiar with the material. If you are new to DragonFly, then you will definitely want to read through this chapter carefully.
736
737 After reading this chapter, you will know:
738
739 * How to use the ***virtual consoles*** of DragonFly.
740
741 * How UNIX file permissions work along with understanding file flags in DragonFly.
742
743 * The default DragonFly file system layout.
744
745 * The DragonFly disk organization.
746
747 * How to mount and unmount file systems.
748
749 * What processes, daemons, and signals are.
750
751 * What a shell is, and how to change your default login environment.
752
753 * How to use basic text editors.
754
755 * What devices and device nodes are.
756
757 * What binary format is used under DragonFly.
758
759 * How to read manual pages for more information.
760
761 ## Virtual Consoles and Terminals 
762
763 DragonFly can be used in various ways. One of them is typing commands to a text terminal. A lot of the flexibility and power of a UNIX® operating system is readily available at your hands when using DragonFly this way. This section describes what ***terminals*** and ***consoles*** are, and how you can use them in !DragonFly.
764
765 <!-- XXX: also mention vesa.ko and other modes for the vt, but maybe somewhere else -->
766
767 ### The Console 
768
769 If you have not configured DragonFly to automatically start a graphical environment during startup, the system will present you with a login prompt after it boots, right after the startup scripts finish running. You will see something similar to:
770
771     Additional ABI support:.
772     Starting cron.
773     Local package initialization:.
774     Additional TCP options:.
775     
776     Wed Feb 18 17:53:48 GMT 2009
777     
778     DragonFly/i386 (Amnesiac) (ttyv0)
779
780     login: 
781
782 The messages might be a bit different on your system, but you will see something similar. The last two lines are what we are interested in right now. The second last line reads:
783
784     DragonFly/i386 (Amnesiac) (ttyv0)
785
786 This line contains some bits of information about the system you have just booted. You are looking at a ***DragonFlyBSD*** console, running on an Intel or compatible processor of the x86 architecture[(1)](#FTN.AEN1036). The name of this machine (every UNIX machine has a name) is `Amnesiac`, and you are now looking at its system console--the `ttyv0` terminal. Finally, the last line is always:
787
788     login:
789
790 This is the part where you are supposed to type in your <i>username</i> to log into DragonFly. The next section describes how you can do this.
791
792 ### Logging into DragonFly 
793
794 DragonFly is a multiuser, multiprocessing system. This is the formal description that is usually given to a system that can be used by many different people, who simultaneously run a lot of programs on a single machine. Every multiuser system needs some way to distinguish one <i>user</i>from the rest. In !DragonFly (and all the UNIX-like operating systems), this is accomplished by requiring that every user must ***log into*** the system before being able to run programs. Every user has a unique name (the <i>username</i> and a personal, secret key (the <i>password</i>). DragonFly will ask for these two before allowing a user to run any programs.
795
796 Right after DragonFly boots and finishes running its startup scripts[(2)](#FTN.AEN1060), it will present you with a prompt and ask for a valid username: 
797
798     login:
799
800 For the sake of this example, let us assume that your username is `john`. Type `john` at this prompt and press  **Enter** . You should then be presented with a prompt to enter a <i>password</i>:
801     
802
803     login: john
804     Password:
805
806 Type in `john`'s password now, and press  **Enter** . The password is <i>not echoed!</i> You need not worry about this right now. Suffice it to say that it is done for security reasons. If you have typed your password correctly, you should by now be logged into DragonFly and ready to try out all the available commands. You should see the MOTD or message of the day followed by a command prompt (a `#`, `$`, or `%` character). This indicates you have successfully logged into DragonFly.
807
808 ### Multiple Consoles 
809
810 Running UNIX commands in one console is fine, but DragonFly can run many programs at once. Having one console where commands can be typed would be a bit of a waste when an operating system like DragonFly can run dozens of programs at the same time. This is where <i>virtual consoles</i> can be very helpful. DragonFly can be configured to present you with many different virtual consoles. You can switch from one of them to any other virtual console by pressing a couple of keys on your keyboard. Each console has its own different output channel, and DragonFly takes care of properly redirecting keyboard input and monitor output as you switch from one virtual console to the next.
811
812 Special key combinations have been reserved by DragonFly for switching consoles[(3)](#FTN.AEN1087). You can use  **Alt** - **F1** ,  **Alt** - **F2** , through  **Alt** - **F8**  to switch to a different virtual console in DragonFly. As you are switching from one console to the next, DragonFly takes care of saving and restoring the screen output. The result is an <i>illusion</i> of having multiple <i>virtual</i> screens and keyboards that you can use to type commands for DragonFly to run. The programs that you launch on one virtual console do not stop running when that console is not visible. They continue running when you have switched to a different virtual console.
813
814 ### The /etc/ttys File 
815
816 The default configuration of DragonFly will start up with eight virtual consoles. This is not a hardwired setting though, and you can easily customize your installation to boot with more or fewer virtual consoles. The number and settings of the virtual consoles are configured in the `/etc/ttys` file.
817
818 You can use the `/etc/ttys` file to configure the virtual consoles of DragonFly. Each uncommented line in this file (lines that do not start with a `#` character) contains settings for a single terminal or virtual console. The default version of this file that ships with DragonFly configures nine virtual consoles, and enables eight of them. They are the lines that start with `ttyv`:
819     
820
821     # name  getty                           type    status          comments
822     #
823     ttyv0   "/usr/libexec/getty Pc"         cons25  on  secure
824     # Virtual terminals
825     ttyv1   "/usr/libexec/getty Pc"         cons25  on  secure
826     ttyv2   "/usr/libexec/getty Pc"         cons25  on  secure
827     ttyv3   "/usr/libexec/getty Pc"         cons25  on  secure
828     ttyv4   "/usr/libexec/getty Pc"         cons25  on  secure
829     ttyv5   "/usr/libexec/getty Pc"         cons25  on  secure
830     ttyv6   "/usr/libexec/getty Pc"         cons25  on  secure
831     ttyv7   "/usr/libexec/getty Pc"         cons25  on  secure
832     ttyv8   "/usr/pkg/xorg/bin/xdm -nodaemon"  xterm   off secure
833
834 For a detailed description of every column in this file and all the options you can use to set things up for the virtual consoles, consult the [ttys(5)](http://leaf.dragonflybsd.org/cgi/web-man?command#ttys&section5) manual page.
835
836 ### Single User Mode Console 
837
838 A detailed description of what <i>single user mode</i> is can be found in [boot-init.html#BOOT-SINGLEUSER Section 7.5.2]. It is worth noting that there is only one console when you are running DragonFly in single user mode. There are no virtual consoles available. The settings of the single user mode console can also be found in the `/etc/ttys` file. Look for the line that starts with `console`:
839
840     
841
842     # name  getty                           type    status          comments
843     #
844     # If console is marked "insecure", then init will ask for the root password
845     # when going to single-user mode.
846     console none                            unknown off secure
847
848  **Note:** As the comments above the `console` line indicate, you can edit this line and change `secure` to `insecure`. If you do that, when DragonFly boots into single user mode, it will still ask for the `root` password. ***Be careful when changing this to insecure***. If you ever forget the `root` password, booting into single user mode is a bit involved. It is still possible, but it might be a bit hard for someone who is not very comfortable with the DragonFly booting process and the programs involved.
849
850 #### Notes 
851
852 [[!table  data="""
853 <tablestyle="width:100%">[ (1)](consoles.html#AEN1036) | This is what `i386` means. Note that even if you are not running DragonFly on an Intel 386 CPU, this is going to be `i386`. It is not the type of your processor, but the processor ***architecture*** that is shown here. 
854  [ (2)](consoles.html#AEN1060) | Startup scripts are programs that are run automatically by DragonFly when booting. Their main function is to set things up for everything else to run, and start any services that you have configured to run in the background doing useful things. 
855  [ (3)](consoles.html#AEN1087) | A fairly technical and accurate description of all the details of the DragonFly console and keyboard drivers can be found in the manual pages of [syscons(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=syscons&section4), [atkbd(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=atkbd&section=4), [vidcontrol(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=vidcontrol&section=1) and [kbdcontrol(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=kbdcontrol&section=1). We will not expand on the details here, but the interested reader can always consult the manual pages for a more detailed and thorough explanation of how things work. |
856
857 """]]
858
859 ## Permissions 
860
861 DragonFly, being a direct descendant of BSD UNIX®, is based on several key UNIX concepts. The first and most pronounced is that DragonFly is a multi-user operating system. The system can handle several users all working simultaneously on completely unrelated tasks. The system is responsible for properly sharing and managing requests for hardware devices, peripherals, memory, and CPU time fairly to each user.
862
863 Because the system is capable of supporting multiple users, everything the system manages has a set of permissions governing who can read, write, and execute the resource. These permissions are stored as three octets broken into three pieces, one for the owner of the file, one for the group that the file belongs to, and one for everyone else. This numerical representation works like this:
864
865 [[!table  data="""
866 |<tablestyle="width:100%"> Value | Permission | Directory Listing 
867 <tablestyle="width:100%"> 0 | No read, no write, no execute | `---` 
868  1 | No read, no write, execute | `--x` 
869  2 | No read, write, no execute | `-w-` 
870  3 | No read, write, execute | `-wx` 
871  4 | Read, no write, no execute | `r--` 
872  5 | Read, no write, execute | `r-x` 
873  6 | Read, write, no execute | `rw-` 
874  7 | Read, write, execute | `rwx` |
875
876 """]]
877
878 You can use the `-l` command line argument to [ls(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ls&section1) to view a long directory listing that includes a column with information about a file's permissions for the owner, group, and everyone else. For example, a `ls -l` in an arbitrary directory may show:
879
880     % ls -l
881     total 530
882     -rw-r--r--  1 root  wheel     512 Sep  5 12:31 myfile
883     -rw-r--r--  1 root  wheel     512 Sep  5 12:31 otherfile
884     -rw-r--r--  1 root  wheel    7680 Sep  5 12:31 email.txt
885     ...
886
887 Here is how the first column of `ls -l` is broken up:    
888
889     -rw-r--r--
890
891 <!-- XXX: Check all these http:// links to see if they are broken -->
892
893 The first (leftmost) character tells if this file is a regular file, a directory, a special character device, a socket, or any other special pseudo-file device. In this case, the `-` indicates a regular file. The next three characters, `rw-` in this example, give the permissions for the owner of the file. The next three characters, `r--`, give the permissions for the group that the file belongs to. The final three characters, `r--`, give the permissions for the rest of the world. A dash means that the permission is turned off. In the case of this file, the permissions are set so the owner can read and write to the file, the group can read the file, and the rest of the world can only read the file. According to the table above, the permissions for this file would be `644`, where each digit represents the three parts of the file's permission.
894
895 This is all well and good, but how does the system control permissions on devices? DragonFly actually treats most hardware devices as a file that programs can open, read, and write data to just like any other file. These special device files are stored on the `/dev` directory.
896
897 Directories are also treated as files. They have read, write, and execute permissions. The executable bit for a directory has a slightly different meaning than that of files. When a directory is marked executable, it means it can be traversed into, that is, it is possible to ***cd*** (change directory) into it. This also means that within the directory it is possible to access files whose names are known (subject, of course, to the permissions on the files themselves).
898
899 In particular, in order to perform a directory listing, read permission must be set on the directory, whilst to delete a file that one knows the name of, it is necessary to have write ***and*** execute permissions to the directory containing the file. There are more permission bits, but they are primarily used in special circumstances such as setuid binaries and sticky directories. If you want more information on file permissions and how to set them, be sure to look at the [chmod(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=chmod&section1) manual page.
900
901 ### Symbolic Permissions 
902
903 ***Contributed by Tom Rhodes.***
904
905 Symbolic permissions, sometimes referred to as symbolic expressions, use characters in place of octal values to assign permissions to files or directories. Symbolic expressions use the syntax of (who) (action) (permissions), where the following values are available:
906
907 [[!table  data="""
908 <tablestyle="width:100%"> Option | Letter | Represents 
909 <tablestyle="width:100%"> (who) | u | User 
910  (who) | g | Group owner 
911  (who) | o | Other 
912  (who) | a | All (***world***) 
913  (action) | + | Adding permissions 
914  (action) | - | Removing permissions 
915  (action) | = | Explicitly set permissions 
916  (permissions) | r | Read 
917  (permissions) | w | Write 
918  (permissions) | x | Execute 
919  (permissions) | t | Sticky bit 
920  (permissions) | s | Set UID or GID |
921
922 """]]
923
924 These values are used with the [chmod(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=chmod&amp;section1) command just like before, but with letters. For an example, you could use the following command to block other users from accessing `FILE`:
925
926     
927
928     % chmod go=FILE
929
930 A comma separated list can be provided when more than one set of changes to a file must be made. For example the following command will remove the groups and ***world*** write permission on `FILE`, then it adds the execute permissions for everyone:
931
932     
933
934     % chmod go-w,a+x FILE
935
936 ### DragonFly File Flags 
937
938 ***Contributed by Tom Rhodes.***
939
940 In addition to file permissions discussed previously, DragonFly supports the use of ***file flags.*** These flags add an additional level of security and control over files, but not directories. These file flags add an additional level of control over files, helping to ensure that in some cases not even the `root` can remove or alter files.  File flags are altered by using the [chflags(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=chflags&amp;section1) utility, using a simple interface. For example, to enable the system undeletable flag on the file `file1`, issue the following command:
941
942     
943
944     # chflags sunlink file1
945
946 And to disable the system undeletable flag, simply issue the previous command with ***no*** in front of the `sunlink`. Observe:
947
948     
949
950     # chflags nosunlink file1
951
952 To view the flags of this file, use the [ls(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ls&amp;section1) with the `-lo` flags:
953
954     
955
956     # ls -lo file1
957
958 The output should look like the following:
959
960     
961
962     -rw-r--r--  1 trhodes  trhodes  sunlnk 0 Mar  1 05:54 file1
963
964 Several flags may only added or removed to files by the `root` user. In other cases, the file owner may set these flags. It is recommended an administrator read over the [chflags(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=chflags&section1) and [chflags(2)](http://leaf.dragonflybsd.org/cgi/web-man?command=chflags&section=2) manual pages for more information.
965
966 ## Directory Structure 
967
968 The DragonFly directory hierarchy is fundamental to obtaining an overall understanding of the system. The most important concept to grasp is that of the root directory, ***/***. This directory is the first one mounted at boot time and it contains the base system necessary to prepare the operating system for multi-user operation. The root directory also contains mount points for every other file system that you may want to mount.
969
970 A mount point is a directory where additional file systems can be grafted onto the root file system. This is further described in [ this Section](disk-organization.html). Standard mount points include `/usr`, `/var`, `/tmp`, `/mnt`, and `/cdrom`. These directories are usually referenced to entries in the file `/etc/fstab`. `/etc/fstab` is a table of various file systems and mount points for reference by the system. Most of the file systems in `/etc/fstab` are mounted automatically at boot time from the script [rc(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rc&section8) unless they contain the `noauto` option. Details can be found in [ this section](mount-unmount.html#DISKS-FSTAB).
971
972 A complete description of the file system hierarchy is available in [hier(7)](http://leaf.dragonflybsd.org/cgi/web-man?command=hier&section7). For now, a brief overview of the most common directories will suffice.
973
974 [[!table  data="""
975 <tablestyle="width:100%">Directory | Description 
976 <tablestyle="width:100%">  `/` | Root directory of the file system. 
977  `/bin/` | User utilities fundamental to both single-user and multi-user environments. 
978  `/boot/` | Programs and configuration files used during operating system bootstrap. 
979  `/boot/defaults/` | Default bootstrapping configuration files; see [loader.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=loader.conf&section5). 
980  `/dev/` | Device nodes; see [intro(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=intro&section4). 
981  `/etc/` | System configuration files and scripts. 
982  `/etc/defaults/` | Default system configuration files; see [rc(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rc&section8). 
983  `/etc/mail/` | Configuration files for mail transport agents such as [sendmail(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=sendmail&section8). 
984  `/etc/namedb/` | `named` configuration files; see [named(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=named&section8). 
985  `/etc/periodic/` | Scripts that are run daily, weekly, and monthly, via [cron(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=cron&section8); see [periodic(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=periodic&section=8). 
986  `/etc/ppp/` | `ppp` configuration files; see [ppp(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=ppp&section8). 
987  `/mnt/` | Empty directory commonly used by system administrators as a temporary mount point. 
988  `/proc/` | Process file system; see [procfs(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=procfs&section5), [mount_procfs(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=mount_procfs&section=8). 
989  `/root/` | Home directory for the `root` account. 
990  `/sbin/` | System programs and administration utilities fundamental to both single-user and multi-user environments. 
991  `/tmp/` | Temporary files. The contents of `/tmp` are usually NOT preserved across a system reboot. A memory-based file system is often mounted at `/tmp`. This can be automated with an entry in `/etc/fstab`; see [mfs(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=mfs&section8). 
992  `/usr/` | The majority of user utilities and applications. 
993  `/usr/bin/` | Common utilities, programming tools, and applications. 
994  `/usr/include/` | Standard C include files. 
995  `/usr/lib/` | Archive libraries. 
996  `/usr/libdata/` | Miscellaneous utility data files. 
997  `/usr/libexec/` | System daemons &amp; system utilities (executed by other programs). 
998  `/usr/local/` | Local executables, libraries, etc. Within `/usr/local`, the general layout sketched out by [hier(7)](http://leaf.dragonflybsd.org/cgi/web-man?command=hier&section7) for `/usr` should be used. An exceptions is the man directory, which is directly under `/usr/local` rather than under `/usr/local/share`. 
999  `/usr/obj/` | Architecture-specific target tree produced by building the `/usr/src` tree. 
1000  `/usr/pkg` | Used as the default destination for the files installed via the pkgsrc® tree or pkgsrc packages (optional). The configuration directory is tunable, but the default location is `/usr/pkg/etc`. 
1001  `/usr/pkg/xorg/` | Xorg distribution executables, libraries, etc (optional). 
1002  `/usr/pkgsrc` | The pkgsrc tree for installing packages (optional). 
1003  `/usr/sbin/` | System daemons &amp; system utilities (executed by users). 
1004  `/usr/share/` | Architecture-independent files. 
1005  `/usr/src/` | BSD and/or local source files. 
1006  `/var/` | Multi-purpose log, temporary, transient, and spool files. A memory-based file system is sometimes mounted at `/var`. This can be automated with an entry in `/etc/fstab`; see [mfs(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=mfs&section8). 
1007  `/var/log/` | Miscellaneous system log files. 
1008  `/var/mail/` | User mailbox files. 
1009  `/var/spool/` | Miscellaneous printer and mail system spooling directories. 
1010  `/var/tmp/` | Temporary files. The files are usually preserved across a system reboot, unless `/var` is a memory-based file system. 
1011  `/var/yp` | NIS maps. |
1012
1013 """]]
1014
1015 ## Disk Organization 
1016
1017 The smallest unit of organization that DragonFly uses to find files is the filename. Filenames are case-sensitive, which means that `readme.txt` and `README.TXT` are two separate files. DragonFly does not use the extension (`.txt`) of a file to determine whether the file is a program, or a document, or some other form of data.
1018
1019 Files are stored in directories.  A directory may contain no files, or it may contain many hundreds of files.  A directory can also contain other directories, allowing you to build up a hierarchy of directories within one another.  This makes it much easier to organize your data.
1020
1021 Files and directories are referenced by giving the file or directory name, followed by a forward slash, `/`, followed by any other directory names that are necessary.  If you have directory `foo`, which contains directory `bar`, which contains the file `readme.txt`, then the full name, or ***path*** to the file is `foo/bar/readme.txt`.
1022
1023 Directories and files are stored in a file system. Each file system contains exactly one directory at the very top level, called the ***root directory*** for that file system.  This root directory can then contain other directories.
1024
1025 So far this is probably similar to any other operating system you may have used.  There are a few differences; for example, MS-DOS® and Windows® use `\`.
1026
1027 DragonFly does not use drive letters, or other drive names in the path. You would not write `c:/foo/bar/readme.txt` on DragonFly.
1028
1029 Instead, one file system is designated the ***root file system***.  The root file system's root directory is referred to as `/`.  Every other file system is then ***mounted*** under the root file system. No matter how many disks you have on your DragonFly system, every directory appears to be part of the same disk.
1030
1031 Suppose you have three file systems, called `A`, `B`, and `C`. Each file system has one root directory, which contains two other directories, called `A1`, `A2` (and likewise `B1`, `B2` and `C1`, `C2`).
1032
1033 Call `A` the root file system. If you used the `ls` command to view the contents of this directory you would see two subdirectories, `A1` and `A2`.  The directory tree looks like this:
1034
1035 <!-- XXX: image -->
1036
1037 A file system must be mounted on to a directory in another file system. So now suppose that you mount file system `B` on to the directory `A1`.  The root directory of `B` replaces `A1`, and the directories in `B` appear accordingly:
1038
1039 <!-- XXX: image -->
1040
1041 Any files that are in the `B1` or `B2` directories can be reached with the path `/A1/B1` or `/A1/B2` as necessary. Any files that were in `/A1` have been temporarily hidden.  They will reappear if `B` is ***unmounted*** from A.
1042
1043 If `B` had been mounted on `A2` then the diagram would look like this:
1044
1045 <!-- XXX: image -->
1046
1047 and the paths would be `/A2/B1` and `/A2/B2` respectively.
1048
1049 File systems can be mounted on top of one another.  Continuing the last example, the `C` file system could be mounted on top of the `B1` directory in the `B` file system, leading to this arrangement:
1050
1051 <!-- XXX: image -->
1052
1053 Or `C` could be mounted directly on to the `A` file system, under the `A1` directory:
1054
1055 <!-- XXX: image -->
1056
1057 If you are familiar with MS-DOS, this is similar, although not identical, to the `join` command.
1058
1059 ## Choosing File System Layout 
1060
1061 This is not normally something you need to concern yourself with. Typically you create file systems when installing DragonFly and decide where to mount them, and then never change them unless you add a new disk.
1062
1063 It is entirely possible to have one large root file system, and not need to create any others. There are some drawbacks to this approach, and one advantage.
1064
1065  **Benefits of Multiple File Systems** 
1066
1067 * Different file systems can have different ***mount options***.  For example, with careful planning, the root file system can be mounted read-only, making it impossible for you to inadvertently delete or edit a critical file.  Separating user-writable file systems, such as `/home`, from other file systems also allows them to be mounted ***nosuid***; this option prevents the ***suid***/***guid*** bits on executables stored on the file system from taking effect, possibly improving security.
1068
1069 * The UFS file system automatically optimizes the layout of files, depending on how the file system is being used. So a file system that contains many small files that are written frequently will have a different optimization to one that contains fewer, larger files.  By having one big file system this optimization breaks down.
1070
1071 * DragonFly's file systems are very robust should you lose power.  However, a power loss at a critical point could still damage the structure of the file system.  By splitting your data over multiple file systems it is more likely that the system will still come up, making it easier for you to restore from backup as necessary. This a major reason to make the root file system of limited size, and with low write activity.
1072
1073  **Benefit of a Single File System** 
1074
1075 * File systems are a fixed size. If you create a file system when you install DragonFly and give it a specific size, you may later discover that you need to make the partition bigger.  The [growfs(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=growfs&amp;section8) command makes it possible to increase the size of a UFS file system on the fly.
1076 <!-- XXX: what about hammer? -->
1077
1078 ## Disk Slices, Partitions and local UNIX file systems 
1079
1080 Here we describe how disks are subdivided.
1081
1082 <!-- XXX: mention serno stuff -->
1083
1084 ### Slices 
1085
1086 A disk can be subdivided in slices.
1087
1088 Slices are named `s0`, `s1` and so on.
1089
1090 For example the disk `ad6` can contain the slice `ad6s3`.
1091
1092 DragonFly support two schemes for slices, MBR and GPT, either of them will manage all slices on a disk:
1093
1094 * MBR: set up using [fdisk(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=fdisk&amp;section8), can be up to 2 TB in size.  MBR slices are numbered from 1; but if disk is ***dangerously dedicated*** it has slice number 0.
1095
1096 * GPT: set up using [gpt(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=gpt&amp;section8), can be extremely large: size up to 8 billion TB.  DragonFly doesn't support booting from a GPT slice in DragonFly  2.0.  Note that GPT slices are numbered from 0. ***Dangerously dedicated*** is not supported nor needed for GPT.  DragonFly 2.1 does have some support for booting from a GPT slice, this is described in [gpt(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=gpt&amp;section=8).
1097
1098 ### Partitions 
1099
1100 Partitions are contained in slices.
1101
1102 Partitions are named `a`, `b` and so on.
1103
1104 DragonFly support 16 partitions per slice, that is `a` through `p`.
1105
1106 For example the partition `ad6s3a` is contained in the slice `ad6s3`.
1107
1108 Partition layout is defined in a label on the slice where the partition reside. DragonFly support two types of disk labels, disklabel32 and disklabel64 (the default):
1109
1110 * [disklabel32(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel&amp;section8): 32 bit disk label which can use slices with size up to 2 TB.
1111
1112 * [disklabel64(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel64&amp;section8): 64 bit disk label which can use very large slices: size up to 16 million TB.
1113
1114 ### Local UNIX file systems 
1115
1116 File systems are contained in partitions.  Each partition can contain only one file system, which means that file systems often are described by either their typical mount point in the file system hierarchy, or the letter of the partition they are contained in.  ***Partition*** does not have the same meaning as the common usage of the term partition (for example, MS-DOS partition), because of DragonFly's UNIX® heritage.
1117
1118 DragonFly support two local UNIX file systems, UFS and HAMMER:
1119
1120 * UFS: The classical BSD UNIX file system, see [ffs(5)](http://leaf.dragonflybsd.org/cgi/web-man?command#ffs&amp;section5), it supports size up to 2 TB.
1121
1122 * [HAMMER(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=HAMMER&amp;section5): A new file system, as of DragonFly 2.0, with many advanced features.  HAMMER file system support size up to 1 million TB.
1123
1124 ### Typical disk layout 
1125
1126 From the above we see the following typical disk layout scenarios:
1127
1128 * For booting DragonFly from a local file system UFS is recommended.  A BOOT+HAMMER setup is recommended for HAMMER use, this consists of a small UFS file system for booting, typically 512MB, and a HAMMER root file system.  The BOOT file system is mounted as /boot after boot.
1129
1130 * For moderate storage requirements UFS can be used; it can be setup on any partition, e.g. on the same disk slice as the boot partition.  HAMMER is an alternative, with extra features supported, like history retention.  You should evaluate if HAMMER is suitable, see note below.
1131
1132 * If really big storage capacity is needed UFS can't fit the need.  You should evaluate if HAMMER is suitable, see note below.  For this use HAMMER needs to be used on a GPT slice with  a [disklabel64(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel64&amp;section8) label.  In DragonFly 2.0 it has to be set up on a disk separate from the boot disk.  In  DragonFly 2.1 one disk can be used for both booting and HAMMER file system on GPT slice, as some support for booting from GPT is present, as described in [gpt(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=gpt&amp;section=8).
1133
1134 ### HAMMER Note 
1135
1136 [HAMMER(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=HAMMER&amp;section5)
1137
1138 is a rather new file system, under active development.
1139
1140 As of DragonFly 2.2.1 release HAMMER is considered production ready.  At 2.0 release it was considered to be in an early Beta state .
1141
1142 All major features except the mirroring are quite well tested as-of the 2.2.1 release.
1143
1144 You should evaluate if HAMMER is suitable for your needs.
1145 <!-- XXX: mention disk and memory requirements for efficient hammer use -->
1146
1147 Examples of ongoing development includes:
1148
1149 * Making HAMMER more self managing; e.g. ability to setup policy for which history to save for how long: e.g. make snapshot every hour and prune and reblock the file system regularly.  When snapshot gets older than 1 month only keep them for every 6 hours; when older than 3 months only keep snapshot for every 24 hours, when older than 3 years only keep snapshot per month.  For now you need to set up [cron(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=cron&amp;section8) jobs for this yourself, see [hammer(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=hammer&amp;section=8).
1150
1151 * Multi master mirroring. For now only one mirror master is supported, but multiple mirror targets, called slaves, are already supported.
1152
1153 * Support for shrinking existing HAMMER file systems.  The HAMMER design is prepared for this, utility just have to be written to support it.
1154 <!-- XXX: is this still accurate? Do we really want to mention it here? -->
1155
1156 ### HAMMER Features 
1157
1158 [HAMMER(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=HAMMER&amp;section5) has several advanced features not found in UFS:
1159
1160 * Large file systems:  Up to 1 million TB, also called 1 Exabyte is supported.
1161
1162 * Multiple volumes:  A HAMMER file system can span up to 256 disks, each partition part of a HAMMER file system is called a volume.  Each volume can be up to 4096 TB in size.
1163
1164 * Support for growing and shrinking existing HAMMER file systems: adding and removing volumes from the file system.  As of 2.4 release an existing HAMMER file system can be expanded by adding extra space, see the `expand` directive to [hammer(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=hammer&amp;section=8).  The HAMMER design is also prepared for removing volumes, utilities just have to be written to support it.
1165
1166 * Instant crash recovery:  If a crash should occur, then HAMMER file systems will be ready a few seconds after boot, no lenghty fsck have to be run.
1167
1168 * Full history retention:  All file system changes are saved every ~30 seconds.  Changes are written at least when sync() is called, see [syncer(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=syncer&amp;section4).  Every time data for files are written to disk a transaction is completed, this is assigned an ID and the file updated can after this be accessed with the contents from this moment.  To access the file with the state of this moment, the transaction ID, TID for brevity, just needs to be added to the file name, like: 'file@@<TID>'.  The TID can be saved from the 'snapshot', 'cleanup', or 'synctid' [hammer(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=hammer&amp;section=8) command or looked up with the 'hammer history file' command.  This history will typically grow over time, so any disk will fill up over time.  Two things are done so disks doesn't fill up: first: big disks are used, at least 50GB is typical for HAMMER file systems, and second: unused history information is deleted regularly. Here we need to define what unused means: a TID is used if a snapshot have been taken on it. Data assigned to unused history can be reclaimed using the `prune` and `reblock` [hammer(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=hammer&amp;section=8) commands, this will also defragment the file system and can be done while the file system is in normal operation.  Generally after file system is pruned only TIDs for the snapshots or newer than newest shapshot should be used, see explanation [here](http://leaf.dragonflybsd.org/mailarchive/bugs/2008-07/msg00213.html) (more info on HAMMER design [here](http://leaf.dragonflybsd.org/mailarchive/kernel/2008-07/msg00114.html)).  See also [hammer(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=hammer&amp;section=5). 
1169
1170 * Mirroring:  A master file system can be mirrored online to a number of slave file systems.  Mirror targets are read-only, but does have history available.  History retension policy can even be different on slaves and master.  Mirroring can be over network and unreliable connections are handled gracefully.
1171
1172 * Data integrity:  HAMMER has high focus in data integrity and implements a CRC checksum on all data, this means that if disk fails with bit errors it will be detected.
1173
1174 More info on HAMMER can be found [here](http://www.dragonflybsd.org/hammer/index.html).
1175
1176 DragonFly also uses disk space for ***swap space***.  Swap space provides DragonFly with ***virtual memory***.  This allows your computer to behave as though it has much more memory than it actually does.  When DragonFly runs low on memory it moves some of the data that is not currently being used to the swap space, and moves it back in (moving something else out) when it needs it.
1177
1178 <!-- XXX: mention swapcache, and also how to configure and use it (somewhere else, probably) -->
1179
1180 ### Adding a Disk 
1181
1182 Adding a disk is done by installing it physically, and to connect it to a disk controller that DragonFly supports.  If you are in doubt if controller is supported, manual pages for disk controllers can be consulted ('man -k disk' or 'man -k scsi' can be of help).  The easiest thing is normally to boot DargonFly with the controller installed and note if boot message contains the controller.
1183
1184 Assuming that disk `ad6` is installed, we could set it up using [fdisk(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=fdisk&amp;section8) and  disklabel(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel&amp;section8) or  [gpt(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=gpt&amp;section8) and 
1185 [disklabel64(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel64&amp;section8).
1186
1187 In this example we choose [gpt(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=gpt&amp;section=8) & [disklabel64(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel64&amp;section=8).
1188
1189 <!-- XXX: mention that disklabel64 is default now -->
1190     
1191
1192     # gpt -v create ad6
1193
1194     ...
1195
1196     # gpt add -s1 ad6
1197
1198     ad6s0
1199
1200     # gpt add ad6
1201
1202     ad6s1
1203
1204     # gpt show ad6
1205
1206     ...
1207
1208 Here we first create the GPT and then add two slices.  In this example the first slice added is `ad6s0`, which is made a dummy slice of size 1 sector, this is just for not having to make further reference to it, as many users remembers that `s0` has special meaning, which really isn't true for GPT slices.  The second slice is `ad6s1` which will cover the rest of the disk.
1209
1210     
1211
1212     # disklabel64 -rw ad6s1 auto
1213
1214     # disklabel64 -e ad6s1          # edit label to add partitions as needed
1215
1216 ### disklabel 
1217 <!-- XXX: what is all this fuzz about dangerously dedicated? -->
1218
1219 For [disklabel(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel&amp;section8) labels some partitions have certain conventions associated with them.
1220
1221 [[!table  data="""
1222 <tablestyle="width:100%"> Partition | Convention 
1223 <tablestyle="width:100%"> `a` | Normally contains the root file system 
1224  `b` | Normally contains swap space 
1225  `c` | Normally the same size as the enclosing slice.  This allows utilities that need to work on the entire slice (for example, a bad block scanner) to work on the `c` partition. You would not normally create a file system on this partition. This is not necessarily true; it is possible to use the 'c' partition as a normal partition.
1226  `d` | Partition `d` used to have a special meaning associated with it, although that is now gone.  To this day, some tools may operate oddly if told to work on partition `d`. |
1227
1228 """]]
1229
1230 Each partition-that-contains-a-file-system is stored in what DragonFly calls a ***slice***.  Slice is DragonFly's term for what the common call partitions, and again, this is because of DragonFly's UNIX background.  Slices are numbered, starting at 1.
1231
1232 Slice numbers follow the device name, prefixed with an `s`, starting at 1. So ***da0s1*** is the first slice on the first SCSI drive. There can only be four physical slices on a disk, but you can have logical slices inside physical slices of the appropriate type.  These extended slices are numbered starting at 5, so ***ad0s5*** is the first extended slice on the first IDE disk. These devices are used by file systems that expect to occupy a slice.
1233
1234 <!-- XXX: gpt allows for way more than 4 partitions... let's remove this stuff above -->
1235
1236 ***Dangerously dedicated*** physical drives are accessed as slice 0.
1237
1238 Slices, ***dangerously dedicated*** physical drives, and other drives contain ***partitions***, which are represented as letters from `a` to `p`.  This letter is appended to the device name, so ***da0s0a*** is the a partition on the first da drive, which is ***dangerously dedicated***. ***ad1s3e*** is the fifth partition in the third slice of the second IDE disk drive.
1239
1240 Finally, each disk on the system is identified.  A disk name starts with a code that indicates the type of disk, and then a number, indicating which disk it is.  Disk numbering starts at 0. Common codes that you will see are listed in [Table 3-1](disk-organization.html#BASICS-DEV-CODES).
1241
1242 <!-- XXX: here would probably be the right place to talk about serno -->
1243
1244 When referring to a partition DragonFly requires that you also name the slice and disk that contains the partition, and when referring to a slice you should also refer to the disk name. Do this by listing the disk name, `s`, the slice number, and then the partition letter.  Examples are shown in [Example 3-1](disk-organization.html#BASICS-DISK-SLICE-PART).
1245
1246 <!-- XXX: later talk also about devfs, definitely not here though. also, devfs rules -->
1247
1248 [Example 3-2](disk-organization.html#BASICS-CONCEPT-DISK-MODEL) shows a conceptual model of the disk layout that should help make things clearer.
1249
1250 In order to install DragonFly you must first configure the disk slices, then create partitions within the slice you will use for DragonFly, and then create a file system (or swap space) in each partition, and decide where that file system will be mounted.
1251
1252 ***'Table 3-1. Disk Device Codes***'
1253
1254 [[!table  data="""
1255 <tablestyle="width:100%"> Code | Meaning 
1256 <tablestyle="width:100%"> `ad` | ATAPI (IDE) disk 
1257  `da` | SCSI direct access disk 
1258  `acd` | ATAPI (IDE) CDROM 
1259  `cd` | SCSI CDROM 
1260  `vn` | Virtual disk
1261  `fd` | Floppy disk |
1262
1263 """]]
1264
1265 ***'Example 3-1. Sample Disk, Slice, and Partition Names***'
1266
1267 [[!table  data="""
1268 <tablestyle="width:100%"> Name | Meaning 
1269 <tablestyle="width:100%"> `ad0s1a` | The first partition (`a`) on the first slice (`s1`) on the first IDE disk (`ad0`). 
1270  `da1s2e` | The fifth partition (`e`) on the second slice (`s2`) on the second SCSI disk (`da1`). |
1271
1272 """]]
1273
1274 ***'Example 3-2. Conceptual Model of a Disk***'
1275
1276 This diagram shows DragonFly's view of the first IDE disk attached to the system. Assume that the disk is 4 GB in size, and contains two 2 GB slices (MS-DOS partitions).  The first slice contains a MS-DOS disk, `C:`, and the second slice contains a DragonFly installation. This example DragonFly installation has three partitions, and a swap partition.
1277
1278 The three partitions will each hold a file system. Partition `a` will be used for the root file system, `e` for the `/var` directory hierarchy, and `f` for the `/usr` directory hierarchy.
1279
1280 <!-- XXX: image -->
1281
1282 ## Mounting and Unmounting File Systems 
1283
1284 The file system is best visualized as a tree, rooted at `/`.
1285
1286 The directories, e.g. `/dev` and `/usr`, in the root directory are branches,
1287
1288 which may have their own branches, such as `/usr/local`, and so on.
1289
1290 There are various reasons to house some of these directories on separate file systems. `/var` contains the directories `log/` and `spool/`, and various types of temporary files, and as such, may get filled up. Filling up the root file system is not a good idea, so splitting `/var` from `/` is often favorable.
1291
1292 Another common reason to contain certain directory trees on other file systems is if they are to be housed on separate physical disks, e.g. CD-ROM, or are used as separate virtual disks, such as [Network File System](network-nfs.html) exports.
1293
1294 ### The fstab File 
1295
1296 During the [boot process](boot.html), file systems listed in `/etc/fstab` are automatically mounted (unless they are listed with the `noauto` option).
1297
1298 The `/etc/fstab` file contains a list of lines of the following format:
1299   
1300
1301     device       mount-point   fstype     options      dumpfreq     passno
1302
1303 These parameters have the following meaning:
1304
1305 * `device`: A device name (which should exist), as explained [here](disks-naming.html).
1306
1307 * `mount-point`: A directory (which should exist), on which to mount the file system.
1308
1309 * `fstype`: The file system type to pass to [mount(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=mount&section8). The default DragonFly file system is `ufs`.
1310
1311 * `options`: Either `rw` for read-write file systems, or `ro` for read-only file systems, followed by any other options that may be needed. A common option is `noauto` for file systems not normally mounted during the boot sequence. Other options are listed in the [mount(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=mount&section8) manual page.
1312
1313 * `dumpfreq`: This is used by [dump(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=dump&section8) to determine which file systems require dumping. If the field is missing, a value of zero is assumed.
1314
1315 * `passno`: This determines the order in which file systems should be checked. File systems that should be skipped should have their `passno` set to zero. The root file system (which needs to be checked before everything else) should have its `passno` set to one, and other file systems' `passno` should be set to values greater than one. If more than one file systems have the same `passno` then [fsck(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=fsck&section8) will attempt to check file systems in parallel if possible.
1316
1317 Consult the [fstab(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=fstab&section5) manual page for more information on the format of the `/etc/fstab` file and the options it contains.
1318
1319 ### The mount Command 
1320
1321 The [mount(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=mount&section8) command is what is ultimately used to mount file systems.
1322
1323 In its most basic form, you use:
1324
1325     
1326
1327     # mount device mountpoint
1328
1329 Or, if `mountpoint` is specified in `/etc/fstab`, just:
1330
1331     
1332
1333     # mount mountpoint
1334
1335 There are plenty of options, as mentioned in the [mount(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=mount&section8) manual page, but the most common are:
1336
1337  **Mount Options** 
1338
1339 * `-a`: Mount all the file systems listed in `/etc/fstab`. Except those marked as `noauto`, excluded by the `-t` flag, or those that are already mounted.
1340
1341 * `-d`: Do everything except for the actual mount system call. This option is useful in conjunction with the `-v` flag to determine what [mount(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=mount&section8) is actually trying to do.
1342
1343 * `-f`: Force the mount of an unclean file system (dangerous), or forces the revocation of write access when downgrading a file system's mount status from read-write to read-only.
1344
1345 * `-r`: Mount the file system read-only. This is identical to using the `rdonly` argument to the `-o` option.
1346
1347 * `-t` ***fstype***: Mount the given file system as the given file system type, or, if used with `-a` option, mount only file systems of the given type. `ufs` is the default file system type.
1348
1349 * `-u`: Update mount options on the file system.
1350
1351 * `-v`: Be verbose.
1352
1353 * `-w`: Mount the file system read-write.
1354
1355 The `-o` option takes a comma-separated list of the options, including the following:
1356
1357 * `nodev:` Do not interpret special devices on the file system. This is a useful security option.
1358
1359 * `noexec`: Do not allow execution of binaries on this file system. This is also a useful security option.
1360
1361 * `nosuid`: Do not interpret setuid or setgid flags on the file system. This is also a useful security option.
1362
1363 ### The umount Command 
1364
1365 The [umount(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=umount&section8) command takes, as a parameter, one of a mountpoint, a device name, or the `-a` or `-A` option.
1366
1367 All forms take `-f` to force unmounting, and `-v` for verbosity. Be warned that `-f` is not generally a good idea. Forcibly unmounting file systems might crash the computer or damage data on the file system.
1368
1369 `-a` and `-A` are used to unmount all mounted file systems, possibly modified by the file system types listed after `-t`. `-A`, however, does not attempt to unmount the root file system.
1370
1371 ## Processes 
1372
1373 DragonFly is a multi-tasking operating system. This means that it seems as though more than one program is running at once. Each program running at any one time is called a ***process***. Every command you run will start at least one new process, and there are a number of system processes that run all the time, keeping the system functional.
1374
1375 <!-- XXX: talk about LWPs and threads? -->
1376
1377 Each process is uniquely identified by a number called a ***process ID***, or ***PID***, and, like files, each process also has one owner and group. The owner and group information is used to determine what files and devices the process can open, using the file permissions discussed earlier. Most processes also have a parent process. The parent process is the process that started them. For example, if you are typing commands to the shell then the shell is a process, and any commands you run are also processes. Each process you run in this way will have your shell as its parent process. The exception to this is a special process called [init(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=init&section8). `init` is always the first process, so its PID is always 1. `init` is started automatically by the kernel when DragonFly starts.
1378
1379 Two commands are particularly useful to see the processes on the system, [ps(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ps&section1) and [top(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=top&section=1). The `ps` command is used to show a static list of the currently running processes, and can show their PID, how much memory they are using, the command line they were started with, and so on. The `top` command displays all the running processes, and updates the display every few seconds, so that you can interactively see what your computer is doing.
1380
1381 By default, `ps` only shows you the commands that are running and are owned by you. For example:
1382
1383     
1384
1385     % ps
1386
1387       PID  TT  STAT      TIME COMMAND
1388       298  p0  Ss     0:01.10 tcsh
1389      7078  p0  S      2:40.88 xemacs mdoc.xsl (xemacs-21.1.14)
1390     37393  p0  I      0:03.11 xemacs freebsd.dsl (xemacs-21.1.14)
1391     48630  p0  S      2:50.89 /usr/local/lib/netscape-linux/navigator-linux-4.77.bi
1392     48730  p0  IW     0:00.00 (dns helper) (navigator-linux-)
1393     72210  p0  R+     0:00.00 ps
1394       390  p1  Is     0:01.14 tcsh
1395      7059  p2  Is+    1:36.18 /usr/local/bin/mutt -y
1396      6688  p3  IWs    0:00.00 tcsh
1397     10735  p4  IWs    0:00.00 tcsh
1398     20256  p5  IWs    0:00.00 tcsh
1399       262  v0  IWs    0:00.00 -tcsh (tcsh)
1400       270  v0  IW+    0:00.00 /bin/sh /usr/X11R6/bin/startx -- -bpp 16
1401       280  v0  IW+    0:00.00 xinit /home/nik/.xinitrc -- -bpp 16
1402       284  v0  IW     0:00.00 /bin/sh /home/nik/.xinitrc
1403       285  v0  S      0:38.45 /usr/X11R6/bin/sawfish
1404
1405 As you can see in this example, the output from [ps(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ps&section1) is organized into a number of columns. `PID` is the process ID discussed earlier. PIDs are assigned starting from 1, go up to 99999, and wrap around back to the beginning when you run out. The `TT` column shows the tty the program is running on, and can safely be ignored for the moment. `STAT` shows the program's state, and again, can be safely ignored. `TIME` is the amount of time the program has been running on the CPU--this is usually not the elapsed time since you started the program, as most programs spend a lot of time waiting for things to happen before they need to spend time on the CPU. Finally, `COMMAND` is the command line that was used to run the program.
1406
1407 [ps(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ps&section1) supports a number of different options to change the information that is displayed. One of the most useful sets is `auxww`. `a` displays information about all the running processes, not just your own. `u` displays the username of the process' owner, as well as memory usage. `x` displays information about daemon processes, and `ww` causes [ps(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ps&section=1) to display the full command line, rather than truncating it once it gets too long to fit on the screen.
1408
1409 The output from [top(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=top&section1) is similar. A sample session looks like this:
1410
1411     
1412
1413     % top
1414     last pid: 72257;  load averages:  0.13,  0.09,  0.03    up 0+13:38:33  22:39:10
1415     47 processes:  1 running, 46 sleeping
1416     CPU states: 12.6% user,  0.0% nice,  7.8% system,  0.0% interrupt, 79.7% idle
1417     Mem: 36M Active, 5256K Inact, 13M Wired, 6312K Cache, 15M Buf, 408K Free
1418     Swap: 256M Total, 38M Used, 217M Free, 15% Inuse
1419     
1420
1421       PID USERNAME PRI NICE  SIZE    RES STATE    TIME   WCPU    CPU COMMAND
1422     72257 nik       28   0  1960K  1044K RUN      0:00 14.86%  1.42% top
1423      7078 nik        2   0 15280K 10960K select   2:54  0.88%  0.88% xemacs-21.1.14
1424       281 nik        2   0 18636K  7112K select   5:36  0.73%  0.73% XF86_SVGA
1425       296 nik        2   0  3240K  1644K select   0:12  0.05%  0.05% xterm
1426     48630 nik        2   0 29816K  9148K select   3:18  0.00%  0.00% navigator-linu
1427       175 root       2   0   924K   252K select   1:41  0.00%  0.00% syslogd
1428      7059 nik        2   0  7260K  4644K poll     1:38  0.00%  0.00% mutt
1429     ...
1430
1431 The output is split into two sections. The header (the first five lines) shows the PID of the last process to run, the system load averages (which are a measure of how busy the system is), the system uptime (time since the last reboot) and the current time. The other figures in the header relate to how many processes are running (47 in this case), how much memory and swap space has been taken up, and how much time the system is spending in different CPU states.
1432
1433 Below that are a series of columns containing similar information to the output from [ps(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ps&section1). As before you can see the PID, the username, the amount of CPU time taken, and the command that was run. [top(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=top&section=1) also defaults to showing you the amount of memory space taken by the process. This is split into two columns, one for total size, and one for resident size--total size is how much memory the application has needed, and the resident size is how much it is actually using at the moment. In this example you can see that  **Netscape®**  has required almost 30 MB of RAM, but is currently only using 9 MB.
1434
1435 [top(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=top&section1) automatically updates this display every two seconds; this can be changed with the `s` option.
1436
1437 ## Daemons, Signals, and Killing Processes 
1438
1439 When you run an editor it is easy to control the editor, tell it to load files, and so on. You can do this because the editor provides facilities to do so, and because the editor is attached to a ***terminal***. Some programs are not designed to be run with continuous user input, and so they disconnect from the terminal at the first opportunity. For example, a web server spends all day responding to web requests, it normally does not need any input from you. Programs that transport email from site to site are another example of this class of application.
1440
1441 We call these programs ***daemons***. Daemons were characters in Greek mythology; neither good or evil, they were little attendant spirits that, by and large, did useful things for mankind. Much like the web servers and mail servers of today do useful things. This is why the mascot for a number of BSD-based operating systems has, for a long time, been a cheerful looking daemon with sneakers and a pitchfork.
1442
1443 There is a convention to name programs that normally run as daemons with a trailing ***d***.  **BIND**  is the Berkeley Internet Name Daemon (and the actual program that executes is called `named`), the  **Apache**  web server program is called `httpd`, the line printer spooling daemon is `lpd` and so on. This is a convention, not a hard and fast rule; for example, the main mail daemon for the  **Sendmail**  application is called `sendmail`, and not `maild`, as you might imagine.
1444
1445 Sometimes you will need to communicate with a daemon process. These communications are called ***signals***, and you can communicate with a daemon (or with any other running process) by sending it a signal. There are a number of different signals that you can send--some of them have a specific meaning, others are interpreted by the application, and the application's documentation will tell you how that application interprets signals. You can only send a signal to a process that you own. If you send a signal to someone else's process with [kill(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=kill&section=1) or [kill(2)](http://leaf.dragonflybsd.org/cgi/web-man?command=kill&section=2) permission will be denied. The exception to this is the `root` user, who can send signals to everyone's processes.
1446
1447 DragonFly will also send applications signals in some cases. If an application is badly written, and tries to access memory that it is not supposed to, DragonFly sends the process the ***Segmentation Violation*** signal (`SIGSEGV`). If an application has used the [alarm(3)](http://leaf.dragonflybsd.org/cgi/web-man?command=alarm&section=3) system call to be alerted after a period of time has elapsed then it will be sent the Alarm signal (`SIGALRM`), and so on.
1448
1449 Two signals can be used to stop a process, `SIGTERM` and `SIGKILL`. `SIGTERM` is the polite way to kill a process; the process can ***catch*** the signal, realize that you want it to shut down, close any log files it may have open, and generally finish whatever it is doing at the time before shutting down. In some cases a process may even ignore `SIGTERM` if it is in the middle of some task that can not be interrupted.
1450
1451 `SIGKILL` can not be ignored by a process. This is the ***I do not care what you are doing, stop right now*** signal. If you send `SIGKILL` to a process then DragonFly will stop that process there and then[(1)](#FTN.AEN2181).
1452
1453 The other signals you might want to use are `SIGHUP`, `SIGUSR1`, and `SIGUSR2`. These are general purpose signals, and different applications will do different things when they are sent.
1454
1455 Suppose that you have changed your web server's configuration file--you would like to tell the web server to re-read its configuration. You could stop and restart `httpd`, but this would result in a brief outage period on your web server, which may be undesirable. Most daemons are written to respond to the `SIGHUP` signal by re-reading their configuration file. So instead of killing and restarting `httpd` you would send it the `SIGHUP` signal. Because there is no standard way to respond to these signals, different daemons will have different behavior, so be sure and read the documentation for the daemon in question.
1456
1457 Signals are sent using the [kill(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=kill&section=1) command, as this example shows.
1458
1459  **Sending a Signal to a Process** 
1460
1461 This example shows how to send a signal to [inetd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=inetd&section=8). The `inetd` configuration file is `/etc/inetd.conf`, and `inetd` will re-read this configuration file when it is sent `SIGHUP`.
1462
1463   1. Find the process ID of the process you want to send the signal to. Do this using [ps(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ps&section=1) and [grep(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=grep&section=1). The [grep(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=grep&section=1) command is used to search through output, looking for the string you specify. This command is run as a normal user, and [inetd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=inetd&section=8) is run as `root`, so the `ax` options must be given to [ps(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ps&section=1).
1464
1465       
1466
1467         % ps -ax | grep inetd
1468
1469         198  ??  IWs    0:00.00 inetd -wW
1470
1471   
1472
1473   So the [inetd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#inetd&section8) PID is 198. In some cases the `grep inetd` command might also occur in this output. This is because of the way [ps(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ps&section=1) has to find the list of running processes.
1474
1475   2. Use [kill(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=kill&section=1) to send the signal. Because [inetd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=inetd&section=8) is being run by `root` you must use [su(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=su&section=1) to become `root` first.
1476
1477       
1478
1479         % su
1480
1481         Password:
1482
1483         # /bin/kill -s HUP 198
1484
1485   
1486
1487   In common with most UNIX® commands, [kill(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=kill&section=1) will not print any output if it is successful. If you send a signal to a process that you do not own then you will see `kill: PID: Operation not permitted`. If you mistype the PID you will either send the signal to the wrong process, which could be bad, or, if you are lucky, you will have sent the signal to a PID that is not currently in use, and you will see `kill: PID: No such process`.
1488
1489 **Why Use `/bin/kill`?** Many shells provide the `kill` command as a built in command; that is, the shell will send the signal directly, rather than running `/bin/kill`. This can be very useful, but different shells have a different syntax for specifying the name of the signal to send. Rather than try to learn all of them, it can be simpler just to use the `/bin/kill ...` command directly.
1490
1491 Sending other signals is very similar, just substitute `TERM` or `KILL` in the command line as necessary.
1492
1493  **Important:** Killing random process on the system can be a bad idea. In particular, [init(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=init&section=8), process ID 1, is very special. Running `/bin/kill -s KILL 1` is a quick way to shutdown your system. ***Always*** double check the arguments you run [kill(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=kill&section=1) with ***before*** you press  **Return** .
1494
1495  
1496  
1497  
1498  
1499  
1500 ## Shells 
1501
1502 In DragonFly, a lot of everyday work is done in a command line interface called a shell. A shell's main job is to take commands from the input channel and execute them. A lot of shells also have built in functions to help everyday tasks such as file management, file globbing, command line editing, command macros, and environment variables. DragonFly comes with a set of shells, such as `sh`, the Bourne Shell, and `tcsh`, the improved C-shell. Many other shells are available from pkgsrc®, such as `zsh` and `bash`.
1503
1504 Which shell do you use? It is really a matter of taste. If you are a C programmer you might feel more comfortable with a C-like shell such as `tcsh`. If you have come from Linux or are new to a UNIX® command line interface you might try `bash`. The point is that each shell has unique properties that may or may not work with your preferred working environment, and that you have a choice of what shell to use.
1505
1506 One common feature in a shell is filename completion. Given the typing of the first few letters of a command or filename, you can usually have the shell automatically complete the rest of the command or filename by hitting the  **Tab**  key on the keyboard. Here is an example. Suppose you have two files called `foobar` and `foo.bar`. You want to delete `foo.bar`. So what you would type on the keyboard is: `rm fo[ **Tab** ].[ **Tab** ]`.
1507
1508 The shell would print out `rm foo[BEEP].bar`.
1509
1510 The [BEEP] is the console bell, which is the shell telling me it was unable to totally complete the filename because there is more than one match. Both `foobar` and `foo.bar` start with `fo`, but it was able to complete to `foo`. If you type in `.`, then hit  **Tab**  again, the shell would be able to fill in the rest of the filename for you.
1511
1512 Another feature of the shell is the use of environment variables. Environment variables are a variable key pair stored in the shell's environment space. This space can be read by any program invoked by the shell, and thus contains a lot of program configuration. Here is a list of common environment variables and what they mean:
1513
1514 [[!table  data="""
1515 <tablestyle="width:100%"> Variable | Description 
1516 <tablestyle="width:100%"> `USER` | Current logged in user's name. 
1517  `PATH` | Colon separated list of directories to search for binaries. 
1518  `DISPLAY` | Network name of the X11 display to connect to, if available. 
1519  `SHELL` | The current shell. 
1520  `TERM` | The name of the user's terminal. Used to determine the capabilities of the terminal. 
1521  `TERMCAP` | Database entry of the terminal escape codes to perform various terminal functions. 
1522  `OSTYPE` | Type of operating system. e.g., DragonFly. 
1523  `MACHTYPE` | The CPU architecture that the system is running on. 
1524  `EDITOR` | The user's preferred text editor. 
1525  `PAGER` | The user's preferred text pager. 
1526  `MANPATH` | Colon separated list of directories to search for manual pages. |
1527
1528 """]]
1529
1530 Setting an environment variable differs somewhat from shell to shell. For example, in the C-Style shells such as `tcsh` and `csh`, you would use `setenv` to set environment variables. Under Bourne shells such as `sh` and `bash`, you would use `export` to set your current environment variables. For example, to set or modify the `EDITOR` environment variable, under `csh` or `tcsh` a command like this would set `EDITOR` to `/usr/pkg/bin/emacs`:
1531     
1532
1533     % setenv EDITOR /usr/pkg/bin/emacs
1534
1535 Under Bourne shells:
1536    
1537
1538     % export EDITOR="/usr/pkg/bin/emacs"
1539
1540 You can also make most shells expand the environment variable by placing a `$` character in front of it on the command line. For example, `echo $TERM` would print out whatever `$TERM` is set to, because the shell expands `$TERM` and passes it on to `echo`.
1541
1542 Shells treat a lot of special characters, called meta-characters as special representations of data. The most common one is the `*` character, which represents any number of characters in a filename. These special meta-characters can be used to do filename globbing. For example, typing in `echo *` is almost the same as typing in `ls` because the shell takes all the files that match `*` and puts them on the command line for `echo` to see.
1543
1544 To prevent the shell from interpreting these special characters, they can be escaped from the shell by putting a backslash (`\`) character in front of them. `echo $TERM` prints whatever your terminal is set to. `echo \$TERM` prints `$TERM` as is.
1545
1546 ### Changing Your Shell 
1547
1548 <!-- XXX: does chsh still exist? chpass will do, too -->
1549
1550 The easiest way to change your shell is to use the `chsh` command. Running `chsh` will place you into the editor that is in your `EDITOR` environment variable; if it is not set, you will be placed in `vi`. Change the ***Shell:*** line accordingly.
1551
1552 You can also give `chsh` the `-s` option; this will set your shell for you, without requiring you to enter an editor. For example, if you wanted to change your shell to `bash`, the following should do the trick:
1553
1554     
1555
1556     % chsh -s /usr/pkg/bin/bash
1557
1558  **Note:** The shell that you wish to use ***must*** be present in the `/etc/shells` file. If you have installed a shell from the [ pkgsrc tree ](pkgsrc.html), then this should have been done for you already. If you installed the shell by hand, you must do this.
1559
1560 For example, if you installed `bash` by hand and placed it into `/usr/local/bin`, you would want to:
1561
1562     
1563
1564     # echo "/usr/local/bin/bash" >> /etc/shells
1565
1566 Then rerun `chsh`.
1567
1568 ## Text Editors 
1569
1570 A lot of configuration in DragonFly is done by editing text files. Because of this, it would be a good idea to become familiar with a text editor. DragonFly comes with a few as part of the base system, and many more are available in the pkgsrc® tree.
1571
1572 The easiest and simplest editor to learn is an editor called  **ee** , which stands for easy editor. To start  **ee** , one would type at the command line `ee filename` where `filename` is the name of the file to be edited. For example, to edit `/etc/rc.conf`, type in `ee /etc/rc.conf`. Once inside of `ee`, all of the commands for manipulating the editor's functions are listed at the top of the display. The caret `^` character represents the  **Ctrl**  key on the keyboard, so `^e` expands to the key combination  **Ctrl** + **e** . To leave  **ee** , hit the  **Esc**  key, then choose leave editor. The editor will prompt you to save any changes if the file has been modified.
1573
1574 DragonFly also comes with more powerful text editors such as  **vi**  as part of the base system, while other editors, like  **emacs**  and  **vim** , are part of the pkgsrc tree. These editors offer much more functionality and power at the expense of being a little more complicated to learn. However if you plan on doing a lot of text editing, learning a more powerful editor such as  **vim**  or  **emacs**  will save you much more time in the long run.
1575
1576 ## Devices and Device Nodes 
1577
1578 A device is a term used mostly for hardware-related activities in a system, including disks, printers, graphics cards, and keyboards. When DragonFly boots, the majority of what DragonFly displays are devices being detected. You can look through the boot messages again by viewing `/var/run/dmesg.boot`.
1579
1580 For example, `acd0` is the first IDE CDROM drive, while `kbd0` represents the keyboard.
1581
1582 Most of these devices in a UNIX® operating system must be accessed through special files called device nodes, which are located in the `/dev` directory.
1583
1584 The device nodes in the `/dev` directory are created and destroyed automatically on DragonFly >= 2.4, by means of the device file system (devfs).
1585
1586 ## Binary Formats 
1587
1588 To understand why DragonFly uses the [elf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=elf&amp;section=5) format, you must first know a little about the three currently ***dominant*** executable formats for UNIX®:
1589
1590 * [a.out(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=a.out&amp;section=5)
1591
1592   The oldest and ***classic*** UNIX object format. It uses a short and compact header with a magic number at the beginning that is often used to characterize the format (see [a.out(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=a.out&amp;section=5) for more details). It contains three loaded segments: .text, .data, and .bss plus a symbol table and a string table.
1593
1594 * <u>COFF</u>
1595
1596   The SVR3 object format. The header now comprises a section table, so you can have more than just .text, .data, and .bss sections.
1597
1598 * [elf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=elf&amp;section=5)
1599
1600   The successor to COFF, featuring multiple sections and 32-bit or 64-bit possible values. One major drawback: ELF was also designed with the assumption that there would be only one ABI per system architecture. That assumption is actually quite incorrect, and not even in the commercial SYSV world (which has at least three ABIs: SVR4, Solaris, SCO) does it hold true. DragonFly tries to work around this problem somewhat by providing a utility for ***branding*** a known ELF executable with information about the ABI it is compliant with. See the manual page for [brandelf(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=brandelf&amp;section=1) for more information. DragonFly runs ELF.
1601
1602 So, why are there so many different formats? Back in the dim, dark past, there was simple hardware. This simple hardware supported a simple, small system. `a.out` was completely adequate for the job of representing binaries on this simple system (a PDP-11). As people ported UNIX from this simple system, they retained the `a.out` format because it was sufficient for the early ports of UNIX to architectures like the Motorola 68k, VAXen, etc.
1603
1604 Then some bright hardware engineer decided that if he could force software to do some sleazy tricks, then he would be able to shave a few gates off the design and allow his CPU core to run faster. While it was made to work with this new kind of hardware (known these days as RISC), `a.out` was ill-suited for this hardware, so many formats were developed to get to a better performance from this hardware than the limited, simple `a.out` format could offer. Things like COFF, ECOFF, and a few obscure others were invented and their limitations explored before things seemed to settle on ELF.
1605
1606 In addition, program sizes were getting huge and disks (and physical memory) were still relatively small so the concept of a shared library was born. The VM system also became more sophisticated. While each one of these advancements was done using the `a.out` format, its usefulness was stretched more and more with each new feature. In addition, people wanted to dynamically load things at run time, or to junk parts of their program after the init code had run to save in core memory and swap space. Languages became more sophisticated and people wanted code called before main automatically. Lots of hacks were done to the `a.out` format to allow all of these things to happen, and they basically worked for a time. In time, `a.out` was not up to handling all these problems without an ever increasing overhead in code and complexity. While ELF solved many of these problems, it would be painful to switch from the system that basically worked. So ELF had to wait until it was more painful to remain with `a.out` than it was to migrate to ELF.
1607
1608 ELF is more expressive than `a.out` and allows more extensibility in the base system. The ELF tools are better maintained, and offer cross compilation support, which is important to many people. ELF may be a little slower than `a.out`, but trying to measure it can be difficult. There are also numerous details that are different between the two in how they map pages, handle init code, etc. None of these are very important, but they are differences.
1609
1610 <!-- XXX: do we really need all this bullshit about file formats? -->
1611
1612 ## For More Information 
1613
1614 ### Manual Pages 
1615
1616 The most comprehensive documentation on DragonFly is in the form of manual pages. Nearly every program on the system comes with a short reference manual explaining the basic operation and various arguments. These manuals can be viewed with the `man` command. Use of the `man` command is simple:
1617
1618     % man command
1619
1620 `command` is the name of the command you wish to learn about. For example, to learn more about `ls` command type:
1621
1622     % man ls
1623
1624 The online manual is divided up into numbered sections:
1625
1626   1. User commands.
1627   1. System calls and error numbers.
1628   1. Functions in the C libraries.
1629   1. Device drivers.
1630   1. File formats.
1631   1. Games and other diversions.
1632   1. Miscellaneous information.
1633   1. System maintenance and operation commands.
1634   1. Kernel internals.
1635
1636 In some cases, the same topic may appear in more than one section of the online manual. For example, there is a `chmod` user command and a `chmod()` system call. In this case, you can tell the `man` command which one you want by specifying the section:
1637     
1638
1639     % man 1 chmod
1640
1641 This will display the manual page for the user command `chmod`. References to a particular section of the online manual are traditionally placed in parenthesis in written documentation, so [chmod(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=chmod&section=1) refers to the `chmod` user command and [chmod(2)](http://leaf.dragonflybsd.org/cgi/web-man?command=chmod&section=2) refers to the system call.
1642
1643 This is fine if you know the name of the command and simply wish to know how to use it, but what if you cannot recall the command name? You can use `man` to search for keywords in the command descriptions by using the `-k` switch:
1644
1645    
1646
1647     % man -k mail
1648
1649 With this command you will be presented with a list of commands that have the keyword ***mail*** in their descriptions. This is actually functionally equivalent to using the `apropos` command.
1650
1651 So, you are looking at all those fancy commands in `/usr/bin` but do not have the faintest idea what most of them actually do? Simply do:    
1652
1653     % cd /usr/bin
1654     % man -f *
1655
1656 or
1657    
1658
1659     % cd /usr/bin
1660     % whatis *
1661
1662 which does the same thing.
1663
1664 ### GNU Info Files 
1665
1666 DragonFly includes many applications and utilities produced by the Free Software Foundation (FSF). In addition to manual pages, these programs come with more extensive hypertext documents called `info` files which can be viewed with the `info` command or, if you installed  **emacs** , the info mode of  **emacs** . To use the [info(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=info&section=1) command, simply type:
1667
1668     % info
1669
1670 For a brief introduction, type `h`. For a quick command reference, type `?`.
1671
1672 # DPorts and pkgng
1673
1674 Dports is DragonFly's own third-party software build system.  It is based on FreeBSD's Ports Collection.  Differences between ports and DPorts are intentionally kept to a minimum, both to maintain familiarity for mutual users of both operating systems and also to leverage the tremendous amount of work the FreeBSD contributors put into ports.  DPorts can and does feature ports unique to DragonFly, so it's truly a native system.
1675
1676 The __pkgng__ tool called "pkg" is a modern and fast binary package manager.  It was developed for FreeBSD, but PC-BSD used it in production first, followed soon after by DragonFly.  In the future, it will be the only binary package manager on FreeBSD, just as DPorts is currently the only port manager.
1677
1678 __pkgng__ is not a replacement for port management tools like `ports-mgmt/portmaster` or `ports-mgmt/portupgrade`. While `ports-mgmt/portmaster` and `ports-mgmt/portupgrade` can install third-party software from both binary packages and DPorts, __pkgng__ installs only binary packages.
1679
1680 ## Getting started with pkgng
1681
1682 DragonFly daily snapshots and Releases (starting with 3.4) come with __pkgng__ already installed.  Upgrades from earlier releases, however, will not have it.  If the "pkg" program is missing on the system for any reason, it can be quickly bootstrapped without having to build it from source.
1683
1684 To ensure  __pkgng__ on a DragonFly BSD 3.4 or higher system is  ready for use, run the following BEFORE you try to use `pkg` the first time:
1685
1686     # cd /usr
1687     # make dports-create
1688     # rm -rf /usr/pkg
1689     # pkg upgrade
1690     # rehash
1691
1692 Since you may need to manually edit the configuration file `/usr/local/etc/pkg.conf`, here is the
1693 usual command to edit it using the vi editor:
1694
1695      # vi /usr/local/etc/pkg.conf
1696
1697 Before using consult the man page (`man pkg`) and then try these examples:
1698
1699     # pkg search editors
1700     # pkg install vim
1701
1702
1703 To bootstrap __pkgng__ with a download on a very old version of DragonFly that is still using `pkgsrc` run:
1704
1705     # make pkg-bootstrap
1706     # rehash
1707     # pkg-static install -y pkg
1708     # rehash
1709
1710 Note that this step is unnecessary for any newly installed release from DragonFly 3.4 onwards.
1711
1712 ## Configuring pkgng
1713
1714 Older versions of pkgng saved their configuration at /usr/local/etc/pkg.conf; this file made reference to a PACKAGESITE.  pkgng will still work based on this file, but will output errors:
1715
1716     # pkg update
1717     pkg: PACKAGESITE in pkg.conf is deprecated. Please create a repository configuration file
1718     Updating repository catalogue
1719     pkg: Warning: use of http:// URL scheme with SRV records is deprecated: switch to pkg+http://
1720
1721 Listen to the errors: hash out the packagesite line, save the file, and move on.  This can be done with vi:
1722
1723     # vi /usr/local/etc/pkg.conf
1724
1725 There will be two lines in the file like this:
1726
1727     # Default Dports package server (California)
1728     PACKAGESITE: http://mirror-master.dragonflybsd.org/dports/${ABI}/LATEST
1729
1730 Hash out the offending line:
1731
1732     # Default Dports package server (California)
1733     # PACKAGESITE: http://mirror-master.dragonflybsd.org/dports/${ABI}/LATEST
1734
1735 Note that, as of time of writing, there are two working package repositories:
1736
1737     # Default Dports package server (California)
1738     # PACKAGESITE: http://mirror-master.dragonflybsd.org/dports/${ABI}/LATEST
1739     
1740     # European mirrors
1741     [...]
1742     #PACKAGESITE: http://dfly.schlundtech.de/dports/${ABI}/LATEST
1743
1744 Test their performance---we will be using the fastest one.  This may, or may not, be the one closest to you (the California site for the New World, the German site for the Old World).
1745
1746     # ping schlundtech.de
1747     PING schlundtech.de (85.236.36.90): 56 data bytes
1748     64 bytes from 85.236.36.90: icmp_seq=0 ttl=49 time=101.433 ms
1749     64 bytes from 85.236.36.90: icmp_seq=1 ttl=49 time=59.177 ms
1750     64 bytes from 85.236.36.90: icmp_seq=2 ttl=49 time=79.550 ms
1751     64 bytes from 85.236.36.90: icmp_seq=3 ttl=49 time=88.268 ms
1752     64 bytes from 85.236.36.90: icmp_seq=4 ttl=49 time=120.060 ms
1753     [...]
1754     --- schlundtech.de ping statistics ---
1755     20 packets transmitted, 19 packets received, 5.0% packet loss
1756     round-trip min/avg/max/stddev = 49.555/96.064/186.662/33.559 ms
1757     # ping mirror-master.dragonflybsd.org
1758     PING avalon.dragonflybsd.org (199.233.90.72): 56 data bytes
1759     64 bytes from 199.233.90.72: icmp_seq=0 ttl=47 time=208.013 ms
1760     64 bytes from 199.233.90.72: icmp_seq=1 ttl=47 time=256.441 ms
1761     64 bytes from 199.233.90.72: icmp_seq=2 ttl=47 time=281.436 ms
1762     64 bytes from 199.233.90.72: icmp_seq=3 ttl=47 time=281.103 ms
1763     64 bytes from 199.233.90.72: icmp_seq=4 ttl=47 time=285.440 ms
1764     [...]
1765     --- avalon.dragonflybsd.org ping statistics ---
1766     19 packets transmitted, 19 packets received, 0.0% packet loss
1767     round-trip min/avg/max/stddev = 208.013/264.017/334.180/31.549 ms
1768
1769 Now, navigate to `/usr/local/etc/pkg/repos/` and rename one of the configuration file samples you find there.  Edit the one you renamed:
1770
1771     # cd /usr/local/etc/pkg/repos/
1772     # ls
1773     df-latest.conf.sample       df-releases.conf.sample
1774     # cp -v df-latest.conf.sample df-latest.conf
1775     df-latest.conf.sample -> df-latest.conf
1776     # chmod -v 644 df-latest.conf
1777     df-latest.conf
1778     # vim df-latest.conf
1779
1780 Enable whichever server was faster (Avalon is American, SchlundTech is German):
1781
1782     Avalon: {
1783         url             : http://mirror-master.dragonflybsd.org/dports/${ABI}/LATEST,
1784         [...]
1785         enabled         : no
1786     }
1787     SchlundTech: {
1788         url             : http://dfly.schlundtech.de/dports/${ABI}/LATEST,
1789         enabled         : yes
1790     }
1791
1792 ## Basic pkgng Operations
1793
1794 Usage information for __pkgng__ is available in the pkg(8) manual page, or by running `pkg` without additional arguments.
1795
1796 Each __pkgng__ command argument is documented in a command-specific manual page. To read the manual page for `pkg install`, for example, run either:
1797
1798     # pkg help install
1799     # man pkg-install
1800
1801 ## Obtaining Information About Installed Packages with pkgng
1802
1803 Information about the packages installed on a system can be viewed by running `pkg info`. Similar to pkg_info(1), the package version and description for all packages will be listed.  Information about a specific package is available by running:
1804
1805     # pkg info packagename
1806
1807 For example, to see which version of __pkgng__ is installed on the system, run:
1808
1809     # pkg info pkg
1810     pkg-1.0.12                   New generation package manager
1811
1812 ## Installing and Removing Packages with pkgng
1813
1814 In general, most DragonFly users will install binary packages by typing:
1815
1816     # pkg install <packagename>
1817
1818 For example, to install curl:
1819
1820     # pkg install curl
1821
1822     Updating repository catalogue
1823     Repository catalogue is up-to-date, no need to fetch fresh copy
1824     The following packages will be installed:
1825     
1826         Installing ca_root_nss: 3.13.5
1827         Installing curl: 7.24.0
1828     
1829     The installation will require 4 MB more space
1830     
1831     1 MB to be downloaded
1832     
1833     Proceed with installing packages [y/N]: y
1834     ca_root_nss-3.13.5.txz           100%    255KB   255.1KB/s  255.1KB/s   00:00
1835     curl-7.24.0.txz                  100%   1108KB     1.1MB/s    1.1MB/s   00:00
1836     Checking integrity... done
1837     Installing ca_root_nss-3.13.5... done
1838     Installing curl-7.24.0... done
1839
1840 The new package and any additional packages that were installed as dependencies can be seen in the installed packages list:
1841
1842     # pkg info
1843     ca_root_nss-3.13.5    The root certificate bundle from the Mozilla Project
1844     curl-7.24.0           Non-interactive tool to get files from FTP, GOPHER, HTTP(S) servers
1845     pkg-1.0.12            New generation package manager
1846
1847 Packages that are no longer needed can be removed with `pkg delete`. For example, if it turns out that curl is not needed after all:
1848
1849     # pkg delete curl
1850     The following packages will be deleted:
1851     
1852         curl-7.24.0_1
1853     
1854     The deletion will free 3 MB
1855     
1856     Proceed with deleting packages [y/N]: y
1857     Deleting curl-7.24.0_1... done
1858
1859 ## Upgrading Installed Packages with pkgng
1860
1861 Packages that are outdated can be found with `pkg version`. If a local ports tree does not exist, pkg-version(8) will use the remote repository catalogue, otherwise the local ports tree will be used to identify package versions.
1862
1863 Packages can be upgraded to newer versions with __pkgng__. Suppose a new version of curl has been released. The local package can be upgraded to the new version:
1864
1865     # pkg upgrade
1866     Updating repository catalogue
1867     repo.txz            100%    297KB   296.5KB/s   296.5KB/s   00:00
1868     The following packages will be upgraded:
1869     
1870     Upgrading curl: 7.24.0 -> 7.24.0_1
1871     
1872     1 MB to be downloaded
1873     
1874     Proceed with upgrading packages [y/N]: y
1875     curl-7.24.0_1.txz   100%    1108KB  1.1MB/s       1.1MB/s   00:00
1876     Checking integrity... done
1877     Upgrading curl from 7.24.0 to 7.24.0_1... done
1878
1879 ## Auditing Installed Packages with pkgng
1880
1881 Occasionally, software vulnerabilities may be discovered in software within DPorts. __pkgng__ includes built-in auditing. To audit the software installed on the system, type:
1882
1883     # pkg audit -F
1884
1885 # Advanced pkgng Operations
1886
1887 ## Automatically Removing Leaf Dependencies with pkgng
1888
1889 Removing a package may leave behind unnecessary dependencies, like `security/ca_root_nss` in the example above. Such packages are still installed, but nothing depends on them any more. Unneeded packages that were installed as dependencies can be automatically detected and removed:
1890
1891     # pkg autoremove
1892     Packages to be autoremoved:
1893         ca_root_nss-3.13.5
1894     
1895     The autoremoval will free 723 kB
1896     
1897     Proceed with autoremoval of packages [y/N]: y
1898     Deinstalling ca_root_nss-3.13.5... done
1899
1900 ## Backing Up the pkgng Package Database
1901
1902 __pkgng__ includes its own package database backup mechanism. To manually back up the package database contents, type:
1903
1904     # pkg backup -d <pkgng.db>
1905
1906 Additionally, __pkgng__ includes a periodic(8) script to automatically back up the package database daily if `daily_backup_pkgng_enable` is set to `YES` in periodic.conf(5).   To prevent the `pkg_install` periodic script from also backing up the package database, set `daily_backup_pkgdb_enable` to `NO` in periodic.conf(5).
1907
1908 To restore the contents of a previous package database backup, run:
1909
1910     # pkg backup -r </path/to/pkgng.db>
1911
1912 ## Removing Stale pkgng Packages
1913
1914 By default, __pkgng__ stores binary packages in a cache directory as defined by `PKG_CACHEDIR` in pkg.conf(5). When upgrading packages with pkg upgrade, old versions of the upgraded packages are not automatically removed.
1915
1916 To remove the outdated binary packages, type:
1917
1918     # pkg clean
1919
1920 ##Modifying pkgng Package Metadata
1921
1922 __pkgng__ has a built-in command to update package origins. For example, if `lang/php5` was originally at version 5.3, but has been renamed to lang/php53 for the inclusion of version 5.4, the package database can be updated to deal with this. For __pkgng__, the syntax is:
1923
1924     # pkg set -o <category/oldport>:<category/newport>
1925
1926 For example, to change the package origin for the above example, type:
1927
1928     # pkg set -o lang/php5:lang/php53
1929
1930 As another example, to update lang/ruby18 to lang/ruby19, type:
1931
1932     # pkg set -o lang/ruby18:lang/ruby19
1933
1934 As a final example, to change the origin of the libglut shared libraries from graphics/libglut to graphics/freeglut, type:
1935
1936     # pkg set -o graphics/libglut:graphics/freeglut
1937
1938 _Note_: When changing package origins, in most cases it is important to reinstall packages that are dependent on the package that has had the origin changed. To force a reinstallation of dependent packages, type:
1939
1940     # pkg install -Rf graphics/freeglut
1941
1942 # Building DPorts from source
1943
1944 The average user will probably not build packages from source.  However, it's easy to do and it can be done even when packages have already been pre-installed on the system.  Common reasons to build from source are:
1945
1946 * The port is new and there's no pre-binary available yet
1947 * The pre-built binaries use the default options and the user needs a package built with a different set of options
1948 * Testing FreeBSD port in order to patch them and submit to DPorts
1949 * The user just prefers building from source
1950
1951 ## Installing DPorts tree
1952
1953 DragonFly 3.4 or later is the minimum version that can build DPorts from source.
1954
1955 It's probably that pkgsrc binaries are already installed because it comes bootstrapped with new systems.  It is necessary to rename `/usr/pkg` directory so that the existing pkgsrc binary tools and libraries don’t get accidentally used while building DPorts, causing breakage.  For the installation of the DPorts tree, type:
1956
1957     # cd /usr
1958     # make dports-create-shallow
1959
1960 If the `/usr/pkg directory` has already been renamed, `git` won’t be in the search path any more.  One option is to download a tarball of DPorts and unpack it.  To do this, type:
1961
1962     # cd /usr
1963     # make dports-download
1964
1965 For future updates, pull delta changes via `git` is fastest, so it is suggested to convert the static tree to a git repository by typing:
1966
1967     # cd /usr/dports/devel/git
1968     # make install
1969     # cd /usr
1970     # rm -rf /usr/dports
1971     # make dports-create-shallow
1972
1973 The git repository is hosted on the [github account of John Marino](https://github.com/jrmarino/DPorts/#readme).
1974
1975 ## Final thoughts
1976
1977 Building from source works similar to ports and pkgsrc: cd into the appropriate program's directory, and type 'make'. 'make install' to install the software, 'make clean' to clean up work files, and so on. Use 'make config-recursive' if you want to set all the port's options, and the options of its dependencies, immediately instead of during the build.
1978
1979 To take all the default build options and avoid getting the pop-up dialog box, set `NO_DIALOG=yes` on either the command line or the make.conf file.
1980
1981 If you just want to set the options for one package, and accept the default for all of its dependencies, do 'make config' in the package in you want non-default options, and then 'make NO_DIALOG=yes'.  Note that this is only necessary if you want to build from source with a non-default set of options, or if no pre-built binary package is available yet.
1982
1983 ## More reading
1984 * How fix/add broken ports: [[docs/howtos/fixdports]]
1985 * [Trick: How to get i386-only software via dports](http://leaf.dragonflybsd.org/mailarchive/users/2013-06/msg00023.html)
1986
1987 # Disclaimer 
1988
1989 DragonFly, up to and including version 3.4, used pkgsrc to manage third party software packages.  DragonFly switched to dports at the 3.6 release.
1990
1991 This page is still useful for anyone wanting to use pkgsrc, but the recommended packaging method is dports, which is covered in a similar document here: 
1992
1993 [http://www.dragonflybsd.org/docs/howtos/HowToDPorts/](http://www.dragonflybsd.org/docs/howtos/HowToDPorts/)
1994
1995 ----
1996
1997 # pkgsrc on DragonFly
1998
1999 DragonFly uses a specially crafted Makefile in /usr and a git mirror
2000 of the official pkgsrc repository to make pkgsrc distribution more user-friendly.
2001
2002 The basics of the pkgsrc system can be found in NetBSD's [Pkgsrc Guide](http://www.netbsd.org/docs/pkgsrc/), and can be considered the canonical resource.
2003
2004
2005
2006
2007 ## Overview 
2008
2009 ### History 
2010 [Pkgsrc](http://www.pkgsrc.org) is a packaging system that was originally created for NetBSD. It has been ported to DragonFly, along with other operating systems.  Pkgsrc is very similar to FreeBSD's ports mechanism.
2011
2012 ### Overview
2013
2014 The pkgsrc collection supplies a collection of files designed to automate the process of compiling an application from source code. Remember that there are a number of steps you would normally carry out if you compiled a program yourself (downloading, unpacking, patching, compiling, installing). The files that make up a pkgsrc source collection contain all the necessary information to allow the system to do this for you. You run a handful of simple commands and the source code for the application is automatically downloaded, extracted, patched, compiled, and installed for you. In fact, the pkgsrc source subsystem can also be used to generate packages which can later be manipulated with `pkg_add` and the other package management commands that will be introduced shortly.
2015
2016 Pkgsrc understands ***dependencies***. Suppose you want to install an application that depends on a specific library being installed. Both the application and the library have been made available through the pkgsrc collection. If you use the `pkg_add` command or the pkgsrc subsystem to add the application, both will notice that the library has not been installed, and automatically install the library first. You might be wondering why pkgsrc® bothers with both. Binary packages and the source tree both have their own strengths, and which one you use will depend on your own preference.
2017
2018  **Binary Package Benefits** 
2019
2020 * A compressed package tarball is typically smaller than the compressed tarball containing the source code for the application.
2021
2022 * Packages do not require any additional compilation. For large applications, such as ***Mozilla***, ***KDE***, or ***GNOME*** this can be important, particularly if you are on a slow system.
2023
2024 * Packages do not require any understanding of the process involved in compiling software on DragonFly.
2025
2026
2027 **Pkgsrc source Benefits** 
2028
2029
2030 * Binary packages are normally compiled with conservative options, because they have to run on the maximum number of systems. By installing from the source, you can tweak the compilation options to (for example) generate code that is specific to a Pentium IV or Athlon processor.
2031
2032 * Some applications have compile time options relating to what they can and cannot do. For example, <i>Apache</i> can be configured with a wide variety of different built-in options. By building from the source you do not have to accept the default options, and can set them yourself. In some cases, multiple packages will exist for the same application to specify certain settings. For example, <i>vim</i> is available as a `vim` package and a `vim-gtk` package, depending on whether you have installed an X11 server. This sort of rough tweaking is possible with packages, but rapidly becomes impossible if an application has more than one or two different compile time options.
2033
2034 * The licensing conditions of some software distributions forbid binary distribution. They must be distributed as source code.
2035
2036 * Some people do not trust binary distributions. With source code, it is possible to check for any vulnerabilities built into the program before installing it to an otherwise secure system. Few people perform this much review, however.
2037
2038 * If you have local patches, you will need the source in order to apply them.
2039
2040 * Some people like having code around, so they can read it if they get bored, hack it, debug crashes, borrow from it (license permitting, of course), and so on.
2041
2042 To keep track of pkgsrc releases subscribe to the [NetBSD pkgsrc users mailing list](http://www.netbsd.org/MailingLists/pkgsrc-users) and the [NetBSD pkgsrc users mailing list](http://www.netbsd.org/MailingLists/tech-pkgsrc). It's also useful to watch the [DragonFly User related mailing list](http://leaf.dragonflybsd.org/mailarchive/) as errors with pkgsrc on DragonFly should be reported there.
2043
2044  **Warning:** Before installing any application, you should check http://www.pkgsrc.org/ for security issues related to your application.
2045
2046 Audit-packages will automatically check all installed applications for known vulnerabilities, a check will be also performed before any application build. Meanwhile, you can use the command `audit-packages -d` after you have installed some packages.
2047
2048 **Note:** Binary packages and source packages are effectively the same software and can be manipulated with the same pkg_* tools.  
2049
2050 ## Installing pkgsrc 
2051
2052 The basic pkgsrc tools are provided with every DragonFly system as part of installation.  However, you still need to download the pkgsrc tree for building applications with these tools.  
2053
2054 Set GITHOST in /etc/make.conf or set it as an environment variable to select a different download location, if desired. See mirrors page for available mirrors.
2055
2056 This downloads the stable version of the pkgsrc tree from the default mirror, if you didn't set GITHOST. As root:
2057
2058     # cd /usr
2059     # make pkgsrc-create
2060
2061 to fetch the intial pkgsrc repository from the net, or
2062
2063     # cd /usr
2064     # make pkgsrc-update
2065
2066 to update.
2067
2068 **Note**: If your DragonFly install is not up to date, you might have ended up with an old release of the pkgsrc tree.
2069
2070     # cd /usr/pkgsrc
2071     # git branch
2072
2073 will show what release you are on. See Tracking the stable branch for more information.
2074
2075 ### Tracking the stable branch
2076
2077 There are quarterly releases of pkgsrc that are specifically designed for stability.  You should in general follow these, rather than the bleeding edge pkgsrc. When a new branch is out you need to set up a local branch tracking that one. 'make pkgsrc-update' will not do this for you.
2078
2079 To see the available remote branches:
2080
2081     # cd /usr/pkgsrc 
2082     # git pull
2083     # git branch -r
2084
2085 To create a local branch, tracking the remote quarterly release:
2086
2087     # cd /usr/pkgsrc 
2088     # git branch pkgsrc-2010Q4 origin/pkgsrc-2010Q4
2089
2090 Branch naming format is 'pkgsrc-YYYYQX', where YYYY is the year and QX is quarters 1-4 of the year.  Check [pkgsrc.org](http://www.pkgsrc.org/) to see the name of the latest stable branch.
2091
2092 After adding a new branch, it can be downloaded with:
2093
2094     # cd /usr/pkgsrc 
2095     # git checkout pkgsrc-2010Q4
2096     # git pull
2097
2098 ## Dealing with pkgsrc packages
2099
2100 The following section explains how to find, install and remove pkgsrc packages.
2101
2102 ### Finding Your Application 
2103
2104 Before you can install any applications you need to know what you want, and what the application is called. DragonFly's list of available applications is growing all the time. Fortunately, there are a number of ways to find what you want:
2105
2106 Since DragonFly 1.11 [pkg_search(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_search&section1) is included in the base system.  [pkg_search(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_search&section=1) searches an already installed pkgsrc INDEX for for a given package name.  If pkgsrc is not installed or the INDEX file is missing, it fetches the [pkg_summary(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_summary&section=5) file.
2107
2108     # pkg_search fvwm
2109     fvwm-2.4.20nb1          Newer version of X11 Virtual window manager
2110     fvwm-2.5.24             Development version of X11 Virtual window manager
2111     fvwm-themes-0.6.2nb8    Configuration framework for fvwm2 with samples
2112     fvwm-wharf-1.0nb1       Copy of AfterStep's Wharf compatible with fvwm2
2113     fvwm1-1.24rnb1          Virtual window manager for X
2114
2115     # pkg_search -v fvwm-2.5
2116     Name    : fvwm-2.5.24-50
2117     Dir     : wm/fvwm-devel                                     
2118     Desc    : Development version of X11 Virtual window manager 
2119     URL     : any                                               
2120     Deps    : perl>#5.0 gettext-lib>0.14.5 [...]
2121
2122 Its also possible to issue the command
2123
2124     # cd /usr/pkgsrc/
2125     # bmake search key='package you are looking for'
2126
2127 from the `/usr/pkgsrc` directory.
2128
2129 It's also possible to browse website that show all the available pkgsrc packages, such as [http://pkgsrc.se/](http://pkgsrc.se) .
2130
2131 ### Installing applications
2132
2133 Downloading a binary package is almost always faster than building from source, but not all programs in pkgsrc can be redistributed as a binary.  In most cases, you will want to download a binary package if possible, and otherwise build from source if it's not available.  
2134
2135 The `bin-install` target on DragonFly (with pkgsrc from 2011/02/07 and later) will do just that:
2136
2137     # cd /usr/pkgsrc/misc/screen
2138     # bmake bin-install clean
2139
2140 This will download and install the appropriate `screen` binary package if it exists, and try building from source if it can't complete the download.
2141
2142 ### Installing applications, source only
2143
2144 Packages are built by going into the appropriate directory and issuing `bmake install clean`. For example, to build the *screen* package you need to issue the following commands.
2145
2146     # cd /usr/pkgsrc/misc/screen
2147     # bmake install clean
2148
2149 To find out the options that can affect how a program is built:
2150
2151     # bmake show-options
2152
2153 To change options:
2154
2155     # bmake PKG_OPTIONS.<package_name>="-option1 option2" install clean
2156
2157 Listing an option enables it.  Listing an option with a "-" before it disables the option.
2158
2159 To make these option changes permanent for every future build or upgrade of this package, put a similar line in `/usr/pkg/etc/mk.conf`:
2160
2161      . PKG_OPTIONS.<package_name>=-option1 option2
2162     
2163 ### Installing applications, binary only
2164
2165 Binary packages can be installed using *pkg_radd*:
2166
2167     # pkg_radd screen
2168
2169 This program works by setting the `PKG_PATH` environment variable to the appropriate path for the operating system and architecture to a remote repository of binary packages, and then using *pkg_add* to get packages. This will install most packages, but will not upgrade packages that are already installed.
2170
2171 You can manually set `BINPKG_BASE` and use *pkg_add* to get the same effect, using a different server.
2172
2173     # setenv BINPKG_BASE http://mirror-master.dragonflybsd.org/packages
2174     # pkg_add screen
2175
2176
2177 #### Issues with pre-built packages
2178
2179 * The default remote repository for binary packages tracks quarterly pkgsrc releases, so your local install of pkgsrc should be the same quarterly release.
2180 * Some packages are not licensed for distribution in binary form, so they may be able to build on DragonFly but won't be available with *pkg_radd*.  If it fails, try going to that package's directory and install the package manually as described above.
2181 * If you upgrade to an new DEVELOPMENT version of DragonFly very early (i.e. shortly after the branch), it might be possible that *pkg_radd* fails to install packages. This is due the fact, that it takes some time to built binary packages and thus, there are no binary packages available on the mirrors yet. Usually you'll see an announcement on the lists once the first packages for DEVELOPMENT are ready.
2182
2183
2184 ### List all installed applications 
2185
2186 To obtain a list of all the packages that are installed on your system:
2187
2188     # pkg_info
2189
2190 To see if certain packages have been installed, filter for the name of the package.  This example will show all *xorg*-related packages currently installed on the system:
2191
2192     # pkg_info | grep xorg
2193
2194 ### Removing packages
2195
2196 If a program was installed as a package:
2197
2198     # pkg_delete packagename
2199
2200 If a package was installed from the source files, you can also change to the directory they were installed from and issue the command:
2201
2202     # bmake deinstall
2203
2204 Note that these methods are effectively interchangeable.  Either will work whether the package was originally installed from source or binary.
2205
2206 #### Remove associated files needed for building a package 
2207
2208 To remove the work file from building a package, and the package's dependencies:
2209
2210     # bmake clean clean-depends
2211
2212 This can be combined with other steps:
2213
2214     # bmake install clean clean-depends
2215
2216 ## Upgrading packages 
2217
2218 There's a number of ways to upgrade pkgsrc; some of these are built in and some are packages installable with pkgsrc.  This list is not necessarily comprehensive.
2219
2220 ### Update pkgsrc system packages
2221
2222 **Note**: Sometimes basic pkgsrc tools; *bmake*, *pkg_install* and *bootstrap-mk-files* need to be upgraded.  However, they can't be deleted and replaced since you need that tool to accomplish replacement.  The solution is to build a separate package before deletion, and install that package. 
2223
2224     # cd /usr/pkgsrc/devel/bmake
2225     or
2226     # cd /usr/pkgsrc/pkgtools/pkg_install
2227     or 
2228     # cd /usr/pkgsrc/pkgtools/bootstrap-mk-files
2229     
2230     # env USE_DESTDIR=yes bmake package
2231     # bmake clean-depends clean
2232
2233 And go to the packages directory and install the binary package with
2234
2235     # cd /usr/pkgsrc/packages/All
2236     # pkg_add -u <pkg_name> (i.e. the name of the .tgz file).
2237
2238
2239 ### bmake replace
2240 Performed in the `/usr/pkgsrc` directory that correlates with the installed package, the software is first built and then replaced.
2241
2242     # cd /usr/pkgsrc/chat/ircII
2243     # bmake replace
2244
2245 ### pkg_rolling-replace
2246
2247 *pkg_rolling-replace* replaces packages one by one and you can use it for a better way of package management. Actually it does `bmake replace` on one package at a time, sorting the packages being replaced according to their interdependencies, which avoids most duplicate rebuilds. Once *pkg_rolling-replace* is installed you can update the packages through the following steps.
2248
2249     # cd /usr && make pkgsrc-update
2250     # pkg_rolling-replace -u
2251
2252 ### pkgin
2253
2254 Downloads and installs binary packages.  Check the [[mirrors]] page for sites carrying binary packages to use with pkgin. You can run the following commands to get the packages updated. This assumes that *pkgin* is already configured. Please consult the documentation and the man page on how to do so.
2255
2256     # pkgin update
2257     # pkgin full-upgrade 
2258
2259 ### pkg_chk
2260
2261 It updates packages by removing them and rebuilding them.  Warning: programs are unavailable until a rebuild finishes.  If they don't rebuild, it won't work. *pkg_chk* requires a few steps in order to work correctly. They are listed here.
2262
2263     # pkg_chk -g  # make initial list of installed packages
2264     # pkg_chk -r  # remove all packages that are not up to date and packages that depend on them
2265     # pkg_chk -a  # install all missing packages (use binary packages, this is the default)
2266     # pkg_chk -as # install all missing packages (build from source)
2267
2268 The above process removes all packages at once and installs the missing packages one by one. This can cause longer disruption of services when the removed package has to wait a long time for its turn to get installed. 
2269
2270 ### pkg_add -u
2271
2272 Point at a local or online binary archive location to download and update packages.
2273
2274 ### rpkgmanager
2275
2276 This requires that you've set up rpkgmanager first. Read more about rpkgmanager [[here|docs/howtos/rpkgmanager/]].
2277
2278     # yes | rpkgmanager.rb
2279
2280 ## Start pkgsrc applications on system startup
2281
2282 Packages often install rc.d scripts to control software running on startup.  To specify where the rc.d scripts from the installed packages should go, add the following lines to your `/usr/pkg/etc/mk.conf` file:
2283
2284     RCD_SCRIPTS_DIR=/etc/rc.d
2285     PKG_RCD_SCRIPTS=YES
2286
2287 This option can be set in the environment to activate it for binary packages.  These packages will still have to be enabled in `/etc/rc.conf/` to run at boot.  If these options aren't set, the rc file will be placed in `/usr/pkg/share/examples/rc.d/` and will need to be manually copied over to `/etc/rc.d`.
2288
2289 Many other options can be set in this file; see `/usr/pkgsrc/mk/defaults/mk.conf` for examples.
2290
2291 ## Miscellaneous topics
2292
2293 ### Post-installation Activities 
2294
2295 After installing a new application you will normally want to read any documentation it may have included, edit any configuration files that are required, ensure that the application starts at boot time (if it is a daemon), and so on.
2296  The exact steps you need to take to configure each application will obviously be different. However, if you have just installed a new application and are wondering *What now?* These tips might help:
2297
2298 Use [pkg_info(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_info&section=1) to find out which files were installed, and where. For example, if you have just installed Foo_Package version 1.0.0, then this command
2299
2300     # pkg_info -L foopackage-1.0.0 | less
2301
2302 will show all the files installed by the package. Pay special attention to files in `man/` directories, which will be manual pages, `etc/` directories, which will be configuration files, and `doc/`, which will be more comprehensive documentation. If you are not sure which version of the application was just installed, a command like this
2303
2304     # pkg_info | grep -i foopackage
2305
2306 will find all the installed packages that have *foopackage* in the package name. Replace *foopackage* in your command line as necessary.
2307
2308 Once you have identified where the application's manual pages have been installed, review them using [man(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=man&section=1). Similarly, look over the sample configuration files, and any additional documentation that may have been provided. If the application has a web site, check it for additional documentation, frequently asked questions, and so forth. If you are not sure of the web site address it may be listed in the output from
2309
2310     # pkg_info foopackage-1.0.0
2311
2312 A `WWW:` line, if present, should provide a URL for the application's web site.
2313
2314 ### Dealing with Broken Packages 
2315
2316 If you come across a package that does not work for you, there are a few things you can do, including:
2317
2318   1. Fix it! The [pkgsrc Guide](http://www.netbsd.org/Documentation/pkgsrc/) includes detailed information on the ***pkgsrc®*** infrastructure so that you can fix the occasional broken package or even submit your own!
2319
2320   1. Send email to the maintainer of the package first. Type `bmake maintainer` or read the `Makefile` to find the maintainer's email address. Remember to include the name and version of the port (send the `$NetBSD:` line from the `Makefile`) and the output leading up to the error when you email the maintainer. If you do not get a response from the maintainer, you can try [users](http://leaf.dragonflybsd.org/mailarchive/) .
2321
2322   1. Grab a pre-built package from an [[mirror|mirrors]] site near you. 
2323
2324 ### What is WIP? 
2325
2326 Packages that can be built within the pkgsrc framework but are not yet necessarily ready for production use can be found in [http://pkgsrc-wip.sourceforge.net](http://pkgsrc-wip.sourceforge.net).  These packages need to be downloaded separately; check the website for details.  Packages in this collection are in development and may not build successfully.
2327
2328 ### Links
2329
2330 * More information: The pkgsrc guide [http://www.netbsd.org/Documentation/pkgsrc/](http://www.netbsd.org/Documentation/pkgsrc/)
2331
2332 * Web interface for searching packages: [http://www.pkgsrc.se](http://www.pkgsrc.se)
2333
2334 * Ways to upgrade packages [http://wiki-static.aydogan.net/How_to_upgrade_packages](http://wiki-static.aydogan.net/How_to_upgrade_packages)
2335
2336 * To search and/or report bugs against packages in pkgsrc, look at [http://www.netbsd.org/support/send-pr.html](http://www.netbsd.org/support/send-pr.html) - use category 'pkg'.
2337
2338 * The #pkgsrc IRC channel on Freenode
2339
2340 * The #dragonflybsd IRC channel on EFnet
2341
2342 # The X Window System 
2343 ***Updated for X.Org's X11 server by Ken Tom and Marc Fonvieille. Updated for DragonFly by Victor Balada Diaz. Updated for 2014 pkgng by Warren Postma***
2344
2345
2346
2347 ## Synopsis 
2348
2349 This chapter will cover the installation and some configuration of the usual way of giving your Dragonfly BSD system an X-Windows style Graphical User Interface (GUI) and a modern Desktop Environment.  In Unix systems, the graphical drawing system is provided by the combination of an X11R6 compliant X-Windows Server, such as the X.org server, and other software such as Window Managers and Desktop Environments.  This multi-layered approach may be surprising to people coming from systems like the Mac or like Windows where these components are not so flexible, or provided by so many separately installed and configured pieces. 
2350
2351 For more information on the video hardware support in X.org, check the [X.org](http://www.x.org/) web site. If you have problems configuring your X server, just search the web. There are lots of tutorials and guides on how to set up your X properly, if the information in this page is not enough for your situation.
2352
2353 Before reading this chapter, you should know how to install additional third-party software. Read the  `dports` section of the documentation, for DragonFly 3.4 and later.
2354
2355 You may find the FreeBSD X Configuration instructions apply exactly and unchanged in DragonFly BSD.
2356 They are found [[here|http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/x-config.html]]
2357
2358 ## Understanding X 
2359
2360 ### What is X.Org
2361
2362 X.Org is the most popular free implementation of the X11 specification.  The X11 specification is an open standard, and there are other implementations, some commercial, and some free.
2363
2364 ### The Window Manager and the Desktop Environment
2365
2366 An X Server is a very low level piece of software.  It does not provide any way to move windows around or resize them. It does not provide a title bar on the top of your windows, or a dock, or any menus.
2367
2368 These things are the job, in the oldest style of X environment, of your window manager, or in more recent times, of a Desktop Environment.
2369
2370 Installing X.org by itself does not give you any window manager or any desktop environment. You will have to choose one and install it yourself. Until you select one, your system will not be usable.
2371
2372 There are dozens of window managers and desktop environments available for X. The most retro ones you might chose include `fvwm` and `twm` which have that retro 1980s workstation look and feel.  There are also window managers included inside modern desktop environments like XFCE, KDE and Gnome.  
2373
2374 If you are brand new and don't know what to do, select the XFCE4 desktop and follow those instructions.
2375 Every desktop environment and window manager also has a different configuration mechanism. Read your chosen environment's documentation to learn more.   Some are configured by text files alone, and some (like KDE and Gnome) have sophisticated graphical configuration utilities and "control panels".
2376
2377 Note that XFCE4 and Gnome and KDE do not require you to install any window manager as they include one automatically.
2378
2379 ## Installing X
2380
2381 **X.org**  is currently available in the DragonFly dports collection.
2382
2383 To install:
2384
2385     pkg install xorg-7.7
2386
2387 By the time you read this, it might be a newer version of xorg than 7.7, you can also try this general command:
2388
2389     pkg install xorg
2390
2391 ## Configuring X
2392
2393 You may need to add the following lines to `/etc/rc.conf` for regular PCs but you might not want to set these two lines to NO instead on a Virtual Machine as they cause problems in Dragonfly BSD 3.4 through 3.6:
2394
2395     hald_enable ="YES"
2396     dbus_enable= "YES" 
2397
2398 Also see below about enabling `moused` in rc.conf, which may be required for you to see your mouse pointer in X.
2399
2400 As of version 7.3, Xorg can often work without any configuration file by simply typing at prompt:
2401
2402     
2403
2404     % startx
2405
2406 If this does not work, or if the default configuration is not acceptable, then X11 must be configured manually.  For example, if X11 does not detect your mouse then you will not get a mouse pointer, you will get a desktop (either a color or a dotted-pattern) but moving your mouse will not result in you seeing a mouse pointer move around.  Also, you might get a garbled display, or no display at all. If any of these happen to you, you need to do some manual configuration of X.org, which means a configuration text file.
2407
2408 Configuration of X11 is a multi-step process. The first step is to build an initial configuration file. As the super user, simply run:
2409    
2410
2411     # Xorg -configure
2412
2413 This will generate an X11 configuration skeleton file in the `/root` directory called `xorg.conf.new` (whether you [su(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=su&amp;section=1) or do a direct login affects the inherited supervisor `$HOME` directory variable). The X11 program will attempt to probe the graphics hardware on the system and write a configuration file to load the proper drivers for the detected hardware on the target system.
2414
2415 The next step is to test the existing configuration to verify that  **X.org**  can work with the graphics hardware on the target system. To perform this task, type:
2416
2417    
2418
2419     # Xorg -config xorg.conf.new -retro
2420
2421 The -retro option is now required or you will only get a black desktop when testing. This retro mode is an empty X desktop with a dot pattern on the background and an X cursor in the center. If the mouse is working, you should be able to move it.
2422
2423 If a black and grey grid and an X mouse cursor appear, the configuration was successful. To exit the test, just press  **Ctrl** + **Alt** + **Backspace**  simultaneously.
2424
2425 **Note:** If the mouse does not work, you will need to first configure it before proceeding. This can usually be achieved by just using `/dev/sysmouse` as the input device in the config file and enabling `moused`:
2426
2427         # rcenable moused
2428
2429 Tune the `xorg.conf.new` configuration file to taste and move it to where [Xorg(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=xorg&section=1) can find it. This is typically `/etc/X11/xorg.conf` or `/usr/pkg/xorg/lib/X11/xorg.conf`.
2430
2431     
2432
2433 The X11 configuration process is now complete. You can start  **X.org**  with [startx(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=startx&section=1). The X11 server may also be started with the use of [xdm(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=xdm&section=1).
2434
2435 ## The X Display Manager 
2436
2437  ***Contributed by Seth Kingsley.***
2438
2439 ### Overview 
2440
2441  The X Display Manager ( **XDM** ) is an optional part of the X Window System that is used for login session management. This is useful for several types of situations, including minimal "X Terminals", desktops, and large network display servers. Since the X Window System is network and protocol independent, there are a wide variety of possible configurations for running X clients and servers on different machines connected by a network.  **XDM**  provides a graphical interface for choosing which display server to connect to, and entering authorization information such as a login and password combination.
2442
2443  Think of  **XDM**  as providing the same functionality to the user as the [getty(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=getty&section=8) utility (see [ Section 17.3.2](term.html#TERM-CONFIG) for details). That is, it performs system logins to the display being connected to and then runs a session manager on behalf of the user (usually an X window manager).  **XDM**  then waits for this program to exit, signaling that the user is done and should be logged out of the display. At this point,  **XDM**  can display the login and display chooser screens for the next user to login.
2444
2445 ### Using XDM 
2446
2447  The  **XDM**  daemon program is located in `/usr/pkg/bin/xdm`. This program can be run at any time as `root` and it will start managing the X display on the local machine. If  **XDM**  is to be run every time the machine boots up, a convenient way to do this is by adding an entry to `/etc/ttys`. For more information about the format and usage of this file, see [ Section 17.3.2.1](term.html#TERM-ETCTTYS). There is a line in the default `/etc/ttys` file for running the  **XDM**  daemon on a virtual terminal:
2448
2449      
2450
2451     ttyv8   "/usr/pkg/bin/xdm -nodaemon"  xterm   off secure
2452
2453  By default this entry is disabled; in order to enable it change field 5 from `off` to `on` and restart [init(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=init&section=8) using the directions in [ Section 17.3.2.2](term.html#TERM-HUP). The first field, the name of the terminal this program will manage, is `ttyv8`. This means that  **XDM**  will start running on the 9th virtual terminal.
2454
2455 ### Configuring XDM 
2456
2457  The  **XDM**  configuration directory is located in `/var/lib/xdm`. The sample configuration files are in `/usr/pkg/share/examples/xdm/`, in this directory there are several files used to change the behavior and appearance of  **XDM** . Typically these files will be found:
2458
2459 [[!table  data="""
2460 <tablestyle="width:100%">  **File**  |  **Description**
2461 <tablestyle="width:100%"> `Xaccess` | Client authorization ruleset.
2462 `Xresources` | Default X resource values.
2463 `Xservers` | List of remote and local displays to manage.
2464 `Xsession` | Default session script for logins.
2465 `Xsetup_`* | Script to launch applications before the login interface.
2466 `xdm-config` | Global configuration for all displays running on this machine.
2467 `xdm-errors` | Errors generated by the server program.
2468 `xdm-pid` | The process ID of the currently running XDM. |
2469
2470 """]]
2471
2472  Also in this directory are a few scripts and programs used to set up the desktop when  **XDM**  is running. The purpose of each of these files will be briefly described. The exact syntax and usage of all of these files is described in [xdm(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=xdm&section=1).
2473
2474  The default configuration is a simple rectangular login window with the hostname of the machine displayed at the top in a large font and "Login:" and "Password:" prompts below. This is a good starting point for changing the look and feel of  **XDM**  screens.
2475
2476 #### Xaccess 
2477
2478  The protocol for connecting to  **XDM**  controlled displays is called the X Display Manager Connection Protocol (XDMCP). This file is a ruleset for controlling XDMCP connections from remote machines. It is ignored unless the `xdm-config` is changed to listen for remote connections. By default, it does not allow any clients to connect.
2479
2480 #### Xresources 
2481
2482  This is an application-defaults file for the display chooser and the login screens. This is where the appearance of the login program can be modified. The format is identical to the app-defaults file described in the X11 documentation.
2483
2484 #### Xservers 
2485
2486  This is a list of the remote displays the chooser should provide as choices.
2487
2488 #### Xsession 
2489
2490  This is the default session script for  **XDM**  to run after a user has logged in. Normally each user will have a customized session script in `~/.xsession` that overrides this script.
2491
2492 #### Xsetup_* 
2493
2494  These will be run automatically before displaying the chooser or login interfaces. There is a script for each display being used, named `Xsetup_` followed by the local display number (for instance `Xsetup_0`). Typically these scripts will run one or two programs in the background such as `xconsole`.
2495
2496 #### xdm-config 
2497
2498  This contains settings in the form of app-defaults that are applicable to every display that this installation manages.
2499
2500 #### xdm-errors 
2501
2502  This contains the output of the X servers that  **XDM**  is trying to run. If a display that  **XDM**  is trying to start hangs for some reason, this is a good place to look for error messages. These messages are also written to the user's `~/.xsession-errors` file on a per-session basis.
2503
2504 ### Running a Network Display Server 
2505
2506  In order for other clients to connect to the display server, edit the access control rules, and enable the connection listener. By default these are set to conservative values. To make  **XDM**  listen for connections, first comment out a line in the `xdm-config` file:
2507
2508      
2509
2510     ! SECURITY: do not listen for XDMCP or Chooser requests
2511
2512     ! Comment out this line if you want to manage X terminals with xdm
2513
2514     DisplayManager.requestPort:     0
2515
2516  and then restart  **XDM** . Remember that comments in app-defaults files begin with a "!" character, not the usual "#". More strict access controls may be desired. Look at the example entries in `Xaccess`, and refer to the [xdm(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=xdm&section=1) manual page for further information.
2517
2518 ### Replacements for XDM 
2519
2520  Several replacements for the default  **XDM**  program exist. One of them,  **kdm**  (bundled with  **KDE** ) is described later in this chapter. The  **kdm**  display manager offers many visual improvements and cosmetic frills, as well as the functionality to allow users to choose their window manager of choice at login time.
2521
2522 ----
2523
2524 ## Desktop Environments 
2525
2526  ***Contributed by Valentino Vaschetto. ***
2527
2528  This section describes the different desktop environments available for X on FreeBSD. A ***desktop environment*** can mean anything ranging from a simple window manager to a complete suite of desktop applications, such as  **KDE**  or  **GNOME** .
2529
2530 ### GNOME 
2531
2532 #### About GNOME 
2533
2534    **GNOME**  is a user-friendly desktop environment that enables users to easily use and configure their computers.  **GNOME**  includes a panel (for starting applications and displaying status), a desktop (where data and applications can be placed), a set of standard desktop tools and applications, and a set of conventions that make it easy for applications to cooperate and be consistent with each other. Users of other operating systems or environments should feel right at home using the powerful graphics-driven environment that  **GNOME**  provides.
2535
2536 #### Installing GNOME 
2537
2538    **GNOME**  can be easily installed from a package or from the pkgsrc framework:
2539
2540   To install the  **GNOME**  package from the network, simply type:
2541
2542     # pkg install gnome-desktop
2543
2544   To build  **GNOME**  from source, if you have the pkgsrc tree on your system:      
2545
2546     # cd /usr/pkgsrc/meta-pkgs/gnome
2547
2548     # bmake install clean
2549
2550   Once  **GNOME**  is installed, the X server must be told to start  **GNOME**  instead of a default window manager.
2551
2552   The easiest way to start  **GNOME**  is with  **GDM** , the GNOME Display Manager.  **GDM** , which is installed as a part of the  **GNOME**  desktop (but is disabled by default), can be enabled by adding `gdm_enable="YES"` to `/etc/rc.conf`. Once you have rebooted,  **GNOME**  will start automatically once you log in -- no further configuration is necessary.
2553
2554 **GNOME**  may also be started from the command-line by properly configuring a file named `.xinitrc`. If a custom `.xinitrc` is already in place, simply replace the line that starts the current window manager with one that starts  **/usr/pkg/bin/gnome-session**  instead. If nothing special has been done to the configuration file, then it is enough simply to type:
2555
2556       
2557
2558     % echo "/usr/pkg/bin/gnome-session" > ~/.xinitrc
2559
2560   Next, type `startx`, and the  **GNOME**  desktop environment will be started.
2561
2562 **Note:** If an older display manager, like  **XDM** , is being used, this will not work. Instead, create an executable `.xsession` file with the same command in it. To do this, edit the file and replace the existing window manager command with  **/usr/pkg/bin/gnome-session** :
2563
2564         
2565
2566     % echo "#!/bin/sh" > ~/.xsession
2567
2568     % echo "/usr/pkg/bin/gnome-session" >> ~/.xsession
2569
2570     % chmod +x ~/.xsession
2571
2572   Yet another option is to configure the display manager to allow choosing the window manager at login time; the section on [ KDE details](x11-wm.html#X11-WM-KDE-DETAILS) explains how to do this for  **kdm** , the display manager of  **KDE** .
2573
2574 #### Anti-aliased Fonts with GNOME 
2575
2576   X11 supports anti-aliasing via its ***RENDER*** extension. GTK+ 2.0 and greater (the toolkit used by  **GNOME** ) can make use of this functionality. Configuring anti-aliasing is described in [ Section 5.5.3](x-fonts.html#ANTIALIAS).
2577   
2578   So, with up-to-date software, anti-aliasing is possible within the  **GNOME**  desktop. Just go to  **Applications->Desktop Preferences->Font** , and select either Best shapes, Best contrast, or Subpixel smoothing (LCDs). For a GTK+ application that is not part of the  **GNOME**  desktop, set the environment variable `GDK_USE_XFT` to `1` before launching the program.
2579
2580 ### KDE 
2581
2582 #### About KDE 
2583
2584   **KDE**  is an easy to use contemporary desktop environment. Some of the things that  **KDE**  brings to the user are:
2585
2586 * A beautiful contemporary desktop
2587
2588 * A desktop exhibiting complete network transparency
2589
2590 * An integrated help system allowing for convenient, consistent access to help on the use of the  **KDE**  desktop and its applications
2591
2592 * Consistent look and feel of all  **KDE**  applications
2593
2594 * Standardized menu and toolbars, keybindings, color-schemes, etc.
2595
2596 * Internationalization:  **KDE**  is available in more than 40 languages
2597
2598 * Centralized consisted dialog driven desktop configuration
2599
2600 * A great number of useful  **KDE**  applications
2601
2602   **KDE**  comes with a web browser called  **Konqueror** , which represents a solid competitor to other existing web browsers on UNIX® systems. More information on  **KDE**  can be found on the [KDE website](http://www.kde.org/).
2603
2604 #### Installing KDE 
2605
2606  Just as with  **GNOME**  or any other desktop environment, the easiest way to install  **KDE**  is through the pkgsrc framework or from a package:
2607
2608  To install the  **KDE**  4.10 package from the network, simply type:
2609
2610    # pkg install kde-4.10
2611
2612  To build  **KDE**  from source, using the pkgsrc framework:
2613
2614     # cd /usr/pkgsrc/meta-pkgs/kde3
2615
2616     # bmake install clean
2617
2618  After  **KDE**  has been installed, the X server must be told to launch this application instead of the default window manager. This is accomplished by editing the `.xinitrc` file:
2619
2620     % echo "exec startkde" > ~/.xinitrc
2621
2622  Now, whenever the X Window System is invoked with `startx`,  **KDE**  will be the desktop.
2623
2624  If a display manager such as  **XDM**  is being used, the configuration is slightly different. Edit the `.xsession` file instead. Instructions for  **kdm**  are described later in this chapter.
2625
2626 #### More Details on KDE 
2627
2628  Now that  **KDE**  is installed on the system, most things can be discovered through the help pages, or just by pointing and clicking at various menus. Windows® or Mac® users will feel quite at home.
2629
2630  The best reference for  **KDE**  is the on-line documentation.  **KDE**  comes with its own web browser,  **Konqueror** , dozens of useful applications, and extensive documentation. The remainder of this section discusses the technical items that are difficult to learn by random exploration.
2631
2632 #### The KDE Display Manager 
2633
2634  An administrator of a multi-user system may wish to have a graphical login screen to welcome users. [ XDM](x-xdm.html) can be used, as described earlier. However,  **KDE**  includes an alternative,  **kdm** , which is designed to look more attractive and include more login-time options. In particular, users can easily choose (via a menu) which desktop environment ( **KDE** ,  **GNOME** , or something else) to run after logging on.
2635
2636  To enable  **kdm** , the `ttyv8` entry in `/etc/ttys` has to be adapted. The line should look as follows:
2637   
2638
2639     ttyv8 "/usr/pkg/bin/kdm -nodaemon" xterm on secure
2640
2641     
2642 ### XFce 
2643
2644 #### About XFce 
2645
2646   **XFce**  is a desktop environment based on the GTK+ toolkit used by  **GNOME** , but is much more lightweight and meant for those who want a simple, efficient desktop which is nevertheless easy to use and configure. Visually, it looks very much like  **CDE** , found on commercial UNIX systems. Some of  **XFce** 's features are:
2647
2648 * A simple, easy-to-handle desktop
2649
2650 * Fully configurable via mouse, with drag and drop, etc
2651
2652 * Main panel similar to  **CDE** , with menus, applets and applications launchers
2653
2654 * Integrated window manager, file manager, sound manager,  **GNOME**  compliance module, and other things
2655
2656 * Themeable (since it uses GTK+)
2657
2658 * Fast, light and efficient: ideal for older/slower machines or machines with memory limitations
2659
2660 More information on  **XFce**  can be found on the [XFce website](http://www.xfce.org/).
2661
2662 #### Installing XFce 
2663
2664  A binary package for  **XFce**  exists. To install, simply type:
2665
2666     # pkg install xfce
2667
2668 This should install the main xfce4 desktop package, and most of the required components.
2669
2670  Alternatively, to build from source, use the pkgsrc framework:
2671
2672    
2673
2674     # cd /usr/pkgsrc/meta-pkgs/xfce4
2675
2676     # bmake install clean
2677
2678  Now, tell the X server to launch  **XFce**  the next time X is started. Simply type this:
2679
2680     % echo "/usr/pkg/bin/startxfce4" > ~/.xinitrc
2681
2682  The next time X is started,  **XFce**  will be the desktop. As before, if a display manager like  **XDM**  is being used, create an `.xsession`, as described in the section on [ GNOME](x11-wm.html#X11-WM-GNOME), but with the `/usr/pkg/bin/startxfce4` command; or, configure the display manager to allow choosing a desktop at login time, as explained in the section on [ kdm](x11-wm.html#X11-WM-KDE-KDM).
2683
2684 <!-- XXX: FreeBSD's handbook has a nice user-oriented section about X applications here. maybe we should have one, too -->
2685
2686 ----
2687
2688 # Configuration and Tuning 
2689
2690 ***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.***
2691
2692
2693
2694 ##Synopsis 
2695
2696 One of the important aspects of DragonFly is system configuration. Correct system configuration will help prevent headaches during future upgrades. This chapter will explain much of the DragonFly configuration process, including some of the parameters which can be set to tune a DragonFly system.
2697
2698 After reading this chapter, you will know:
2699
2700 * How to efficiently work with file systems and swap partitions.
2701
2702 * The basics of `rc.conf` configuration and `rc.d` startup systems.
2703
2704 * How to configure and test a network card.
2705
2706 * How to configure virtual hosts on your network devices.
2707
2708 * How to use the various configuration files in `/etc`.
2709
2710 * How to tune DragonFly using `sysctl` variables.
2711
2712 * How to tune disk performance and modify kernel limitations.
2713
2714 Before reading this chapter, you should:
2715
2716 * Understand UNIX® and DragonFly basics ([Chapter 3](basics.html)).
2717
2718 * Be familiar with the basics of kernel configuration/compilation ([Chapter 9](kernelconfig.html)).
2719
2720 ## Initial Configuration 
2721
2722 ### Partition Layout 
2723
2724 #### Base Partitions 
2725
2726 When laying out file systems with [disklabel(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel&section=8) remember that hard drives transfer data faster from the outer tracks to the inner. Thus smaller and heavier-accessed file systems should be closer to the outside of the drive, while larger partitions like `/usr` should be placed toward the inner. It is a good idea to create partitions in a similar order to: root, swap, `/var`, `/usr`.
2727 <!-- XXX: on the advent of SSDs, do we really need to talk about this stuff? Who knows where on the platter the partitions land, considering that a hard disk has multiple platters? -->
2728
2729 The size of `/var` reflects the intended machine usage. `/var` is used to hold mailboxes, log files, and printer spools. Mailboxes and log files can grow to unexpected sizes depending on how many users exist and how long log files are kept. Most users would never require a gigabyte, but remember that `/var/tmp` must be large enough to contain packages.
2730
2731 The `/usr` partition holds much of the files required to support the system, the pkgsrc® collection (recommended) and the source code (optional). At least 2 gigabytes would be recommended for this partition.
2732
2733 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.
2734
2735 #### Swap Partition 
2736
2737 As a rule of thumb, the swap partition should be about double the size of system memory (RAM). For example, if the machine has 128 megabytes of memory, the swap file should be 256 megabytes. Systems with less memory may perform better with more swap. Less than 256 megabytes of swap is not recommended and memory expansion should be considered. The kernel's VM paging algorithms are tuned to perform best when the swap partition is at least two times the size of main memory. Configuring too little swap can lead to inefficiencies in the VM page scanning code and might create issues later if more memory is added.
2738 <!-- XXX: do we really recommend double the RAM for swap? IMHO the amount of RAM should be more than enough -->
2739
2740 On larger systems with multiple SCSI disks (or multiple IDE disks operating on different controllers), it is recommend that a swap is configured on each drive (up to four drives). The swap partitions should be approximately the same size. The kernel can handle arbitrary sizes but internal data structures scale to 4 times the largest swap partition. Keeping the swap partitions near the same size will allow the kernel to optimally stripe swap space across disks. Large swap sizes are fine, even if swap is not used much. It might be easier to recover from a runaway program before being forced to reboot.
2741
2742 #### Why Partition? 
2743
2744 Several users think a single large partition will be fine, but there are several reasons why this is a bad idea. First, each partition has different operational characteristics and separating them allows the file system to tune accordingly. For example, the root and `/usr` partitions are read-mostly, without much writing. While a lot of reading and writing could occur in `/var` and `/var/tmp`.
2745
2746 By properly partitioning a system, fragmentation introduced in the smaller write heavy partitions will not bleed over into the mostly-read partitions. Keeping the write-loaded partitions closer to the disk's edge, will increase I/O performance in the partitions where it occurs the most. Now while I/O performance in the larger partitions may be needed, shifting them more toward the edge of the disk will not lead to a significant performance improvement over moving `/var` to the edge. Finally, there are safety concerns. A smaller, neater root partition which is mostly read-only has a greater chance of surviving a bad crash.
2747 <!-- XXX: again, same story about the edges of disks... -->
2748
2749 CategoryHandbook
2750
2751 CategoryHandbook-configuration
2752
2753 ## Core Configuration 
2754
2755 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.
2756
2757 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.
2758
2759 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.
2760
2761 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:
2762
2763 * rc.conf:
2764
2765         hostname="node15.example.com"
2766
2767         network_interfaces="fxp0 lo0"
2768
2769         ifconfig_fxp0="inet 10.1.1.1"
2770
2771   
2772
2773 * rc.conf.site: 
2774
2775         defaultrouter="10.1.1.254"
2776
2777         saver="daemon"
2778
2779         blanktime="100"
2780
2781   
2782
2783 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.
2784
2785 Upgrading the system using `make world` will not overwrite the `rc.conf` file, so system configuration information will not be lost.
2786
2787 CategoryHandbook
2788
2789 CategoryHandbook-configuration
2790
2791 ## Application Configuration 
2792
2793 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.
2794
2795 Typically, these files are installed in `/usr/pkg/etc`. In the case where an application has a large number of configuration files, a subdirectory will be created to hold them.
2796
2797 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.
2798
2799 For example, consider the contents of the directory `/usr/pkg/etc/httpd`:
2800
2801     
2802
2803     total 90
2804
2805     -rw-r--r--  1 root  wheel  -   34K Jan 11 12:04 httpd.conf
2806
2807     -rw-r--r--  1 root  wheel  -   13K Jan 11 12:02 magic
2808
2809     -rw-r--r--  1 root  wheel  -   28K Jan 11 12:02 mime.types
2810
2811     -rw-r--r--  1 root  wheel  -   11K Jan 11 12:02 ssl.conf
2812
2813     
2814     
2815     
2816     
2817     
2818
2819 ## Starting Services 
2820
2821 It is common for a system to host a number of services. These may be started in several different fashions, each having different advantages.
2822
2823 Software installed from a port or the packages collection will often place a script in `/usr/pkg/share/examples/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.
2824
2825 A generic startup script in `/usr/pkg/share/examples/rc.d` looks like:
2826
2827     
2828
2829     #!/bin/sh
2830
2831     echo -n ' FooBar'
2832
2833     
2834
2835     case "$1" in
2836
2837     start)
2838
2839             /usr/pkg/bin/foobar
2840
2841             ;;
2842
2843     stop)
2844
2845             kill -9 `cat /var/run/foobar.pid`
2846
2847             ;;
2848
2849     
2850 *)
2851
2852             echo "Usage: `basename $0` {start|stop}" >&2
2853
2854             exit 64
2855
2856             ;;
2857
2858     esac
2859
2860     
2861
2862     exit 0
2863
2864     
2865
2866 <!-- XXX: I don't think we actually look in /usr/pkg/share/examples/rc.d -->
2867
2868 The startup scripts of DragonFly will look in `/usr/pkg/share/examples/rc.d` for scripts that have an `.sh` extension and are executable by `root`. Those scripts that are found are called with an option `start` at startup, and `stop` at shutdown to allow them to carry out their purpose. So if you wanted the above sample script to be picked up and run at the proper time during system startup, you should save it to a file called `FooBar.sh` in `/usr/local/etc/rc.d` and make sure it is executable. You can make a shell script executable with [chmod(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=chmod&section=1) as shown below:
2869
2870     
2871
2872     # chmod 755 "FooBar.sh"
2873
2874 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.
2875
2876 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.
2877
2878  **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/pkg/share/examples/rc.d` instead.
2879
2880 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.
2881
2882 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.
2883
2884 CategoryHandbook
2885
2886 CategoryHandbook-configuration
2887
2888 ## Configuring the cron Utility 
2889
2890 <!-- XXX: can't really comment on this. someone please revise it -->
2891
2892 ***Contributed by Tom Rhodes. ***
2893
2894 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.
2895
2896 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.
2897
2898  **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.
2899
2900 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`.
2901
2902 Let us take a look at the `/etc/crontab` file (the system crontab):
2903
2904     
2905
2906     # /etc/crontab - root's crontab for DragonFly
2907
2908     #
2909
2910     #                                                                  (1)
2911
2912     #
2913
2914     SHELL=/bin/sh
2915
2916     PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin                            (2)
2917
2918     HOME=/var/log
2919
2920     #
2921
2922     #
2923
2924     #minute     hour    mday    month   wday    who     command            (3)
2925
2926     #
2927
2928     #
2929
2930     
2931     */5 *       *       *       *       root    /usr/libexec/atrun (4)
2932
2933  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.
2934
2935  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.
2936
2937  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.
2938
2939  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.
2940
2941 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.
2942
2943 ### Installing a Crontab 
2944
2945  **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.
2946
2947 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:
2948
2949     
2950
2951     % crontab crontab-file
2952
2953 In this example, `crontab-file` is the filename of a `crontab` that was previously created.
2954
2955 There is also an option to list installed `crontab` files: just pass the `-l` option to `crontab` and look over the output.
2956
2957 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.
2958
2959 If you later want to remove your user `crontab` completely, use `crontab` with the `-r` option.
2960
2961 ## Using rc under DragonFly 
2962
2963 ***Contributed by Tom Rhodes. ***
2964
2965 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:
2966
2967     
2968
2969     # /etc/rc.d/sshd restart
2970
2971 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`:
2972
2973     natd_enable="YES"
2974
2975 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.
2976
2977 Another way to add services to the automatic startup/shutdown is to type, for example for `natd`,
2978
2979      # rcenable natd
2980
2981 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:
2982
2983     
2984
2985     # /etc/rc.d/sshd forcerestart
2986
2987 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:
2988
2989     
2990
2991     # /etc/rc.d/sshd rcvar
2992
2993     # sshd
2994
2995     $sshd_enable=YES
2996
2997  **Note:** The second line (`# sshd`) is the output from the `rc.d` script, not a `root` prompt.
2998
2999 To determine if a service is running, a `status` option is available. For instance to verify that `sshd` is actually started:
3000
3001     
3002
3003     # /etc/rc.d/sshd status
3004
3005     sshd is running as pid 433.
3006
3007 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.
3008
3009 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.
3010
3011 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:
3012
3013 * `PROVIDE`: Specifies the services this file provides.
3014
3015 * `REQUIRE`: Lists services which are required for this service. This file will run ***after*** the specified services.
3016
3017 * `BEFORE`: Lists services which depend on this service. This file will run ***before*** the specified services.
3018
3019 * 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.
3020
3021   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.
3022
3023 By using this method, an administrator can easily control system services without the hassle of ***runlevels*** like some other UNIX® operating systems.
3024
3025 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.
3026
3027 ### Using DragonFly's rcrun(8) 
3028
3029 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)
3030
3031 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.
3032
3033 The remaining commands are:
3034
3035 [[!table  data="""
3036   **disable**  | Sets the corresponding `_enable` variable in rc.conf(5) to ***NO*** and runs the stop command. 
3037   **enable**   | Sets the corresponding `_enable` variable in rc.conf(5) to ***YES*** and runs the start command. 
3038   **list**  | Shows the status of the specified scripts.  If no argument is specified, the status of all scripts is shown. |
3039
3040 """]]
3041
3042 To enable the [dntpd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=dntpd&section=8) service, you can use:
3043
3044      # rcenable dntpd
3045      
3046  
3047
3048 To check if [dntpd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=dntpd&section=8) is running you can use the following command:
3049
3050     
3051
3052     # rclist dntpd
3053
3054     rcng_dntpd=stopped
3055
3056 To start [dntpd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=dntpd&section=8):
3057
3058     
3059
3060     # rcstart dntpd
3061
3062     Running /etc/rc.d/dntpd start
3063
3064     Starting dntpd.
3065
3066 Restart and stop works the same way:
3067
3068     
3069
3070     # rcrestart dntpd
3071
3072     Stopping dntpd.
3073
3074     Starting dntpd.
3075
3076     
3077
3078     # rcstop dntpd
3079
3080     Stopping dntpd.
3081
3082 If a service is not enabled in `/etc/rc.conf`, but you want it start anyway, execute the following:
3083
3084     
3085
3086     # rcforce dntpd
3087
3088     Running /etc/rc.d/dntpd forcestart
3089
3090     Starting dntpd.
3091
3092 #### Notes 
3093
3094 [[!table  data="""
3095 <tablestyle="width:100%"> [(1)](configtuning-rcng.html#AEN4751) | Previously this was used to define *BSD dependent features.
3096 | |
3097
3098 """]]
3099
3100 ## Setting Up Network Interface Cards 
3101
3102 ***Contributed by Marc Fonvieille. ***
3103
3104 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.
3105
3106 ### Locating the Correct Driver 
3107
3108 Before you begin, you should know the model of the card you have, the chip it uses, and whether it is a PCI or ISA card. DragonFly supports a wide variety of both PCI and ISA cards. Check the Hardware Compatibility List for your release to see if your card is supported.
3109
3110 Once you are sure your card is supported, you need to determine the proper driver for the card. The file `/usr/src/sys/i386/conf/LINT` will give you the list of network interfaces drivers with some information about the supported chipsets/cards. 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.
3111
3112 If you own a common card, most of the time you will not have to look very hard for a driver. Drivers for common network cards are present in the `GENERIC` kernel, so your card should show up during boot, like so:
3113
3114     
3115
3116     dc0: <82c169 PNIC 10/100BaseTX> port 0xa000-0xa0ff mem 0xd3800000-0xd38
3117
3118     000ff irq 15 at device 11.0 on pci0
3119
3120     dc0: Ethernet address: 00:a0:cc:da:da:da
3121
3122     miibus0: <MII bus> on dc0
3123
3124     ukphy0: <Generic IEEE 802.3u media interface> on miibus0
3125
3126     ukphy0:  10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto
3127
3128     dc1: <82c169 PNIC 10/100BaseTX> port 0x9800-0x98ff mem 0xd3000000-0xd30
3129
3130     000ff irq 11 at device 12.0 on pci0
3131
3132     dc1: Ethernet address: 00:a0:cc:da:da:db
3133
3134     miibus1: <MII bus> on dc1
3135
3136     ukphy1: <Generic IEEE 802.3u media interface> on miibus1
3137
3138     ukphy1:  10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto
3139
3140 In this example, we see that two cards using the [dc(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=dc&section=4) driver are present on the system.
3141
3142 To use your network card, you will need to load the proper driver. This may be accomplished in one of two ways. The easiest way is to simply load a kernel module for your network card with [kldload(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=kldload&section=8). A module is not available for all network card drivers (ISA cards and cards using the [ed(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=ed&section=4) driver, for example). Alternatively, you may statically compile the support for your card into your kernel. Check `/usr/src/sys/i386/conf/LINT` and the manual page of the driver to know what to add in your kernel configuration file. For more information about recompiling your kernel, please see [kernelconfig.html Chapter 9]. If your card was detected at boot by your kernel (`GENERIC`) you do not have to build a new kernel.
3143
3144 ### Configuring the Network Card 
3145
3146 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.
3147
3148 To display the configuration for the network interfaces on your system, enter the following command:
3149
3150     
3151
3152     % ifconfig
3153
3154     dc0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
3155
3156             inet 192.168.1.3 netmask 0xffffff00 broadcast 192.168.1.255
3157
3158             ether 00:a0:cc:da:da:da
3159
3160             media: Ethernet autoselect (100baseTX <full-duplex>)
3161
3162             status: active
3163
3164     dc1: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
3165
3166             inet 10.0.0.1 netmask 0xffffff00 broadcast 10.0.0.255
3167
3168             ether 00:a0:cc:da:da:db
3169
3170             media: Ethernet 10baseT/UTP
3171
3172             status: no carrier
3173
3174     lp0: flags=8810<POINTOPOINT,SIMPLEX,MULTICAST> mtu 1500
3175
3176     lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> mtu 16384
3177
3178             inet 127.0.0.1 netmask 0xff000000
3179
3180     tun0: flags=8010<POINTOPOINT,MULTICAST> mtu 1500
3181
3182  **Note:** Note that entries concerning IPv6 (`inet6` etc.) were omitted in this example.
3183
3184 In this example, the following devices were displayed:
3185
3186 * `dc0`: The first Ethernet interface
3187
3188 * `dc1`: The second Ethernet interface
3189
3190 * `lp0`: The parallel port interface
3191
3192 * `lo0`: The loopback device
3193
3194 * `tun0`: The tunnel device used by  **ppp** 
3195
3196 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.
3197
3198 In this example, the `dc0` device is up and running. The key indicators are:
3199
3200   1. `UP` means that the card is configured and ready.
3201
3202   1. The card has an Internet (`inet`) address (in this case `192.168.1.3`).
3203
3204   1. It has a valid subnet mask (`netmask`; `0xffffff00` is the same as `255.255.255.0`).
3205
3206   1. It has a valid broadcast address (in this case, `192.168.1.255`).
3207
3208   1. The MAC address of the card (`ether`) is `00:a0:cc:da:da:da`
3209
3210   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.
3211
3212   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.
3213
3214 If the [ifconfig(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=ifconfig&section=8) output had shown something similar to:
3215
3216     
3217
3218     dc0: flags=8843<BROADCAST,SIMPLEX,MULTICAST> mtu 1500
3219
3220                 ether 00:a0:cc:da:da:da
3221
3222 it would indicate the card has not been configured.
3223
3224 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.
3225
3226     
3227
3228     # ifconfig dc0 inet 192.168.1.3 netmask 255.255.255.0
3229
3230 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.
3231
3232 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:
3233
3234     
3235
3236     ifconfig_dc0="inet 192.168.1.3 netmask 255.255.255.0"
3237
3238     ifconfig_dc1="inet 10.0.0.1 netmask 255.255.255.0 media 10baseT/UTP"
3239
3240 You have to replace `dc0`, `dc1`, 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`.
3241
3242 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.
3243
3244 You will 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`.
3245
3246 ### Testing and Troubleshooting 
3247
3248 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.
3249
3250 Once the system has been rebooted, you should test the network interfaces.
3251
3252 #### Testing the Ethernet Card 
3253
3254 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.
3255
3256 First test the local interface:
3257
3258     
3259
3260     % ping -c5 192.168.1.3
3261
3262     PING 192.168.1.3 (192.168.1.3): 56 data bytes
3263
3264     64 bytes from 192.168.1.3: icmp_seq#0 ttl64 time=0.082 ms
3265
3266     64 bytes from 192.168.1.3: icmp_seq#1 ttl64 time=0.074 ms
3267
3268     64 bytes from 192.168.1.3: icmp_seq#2 ttl64 time=0.076 ms
3269
3270     64 bytes from 192.168.1.3: icmp_seq#3 ttl64 time=0.108 ms
3271
3272     64 bytes from 192.168.1.3: icmp_seq#4 ttl64 time=0.076 ms
3273
3274     
3275
3276     --- 192.168.1.3 ping statistics ---
3277
3278     5 packets transmitted, 5 packets received, 0% packet loss
3279
3280     round-trip min/avg/max/stddev = 0.074/0.083/0.108/0.013 ms
3281
3282 Now we have to ping another machine on the LAN:
3283
3284     
3285
3286     % ping -c5 192.168.1.2
3287
3288     PING 192.168.1.2 (192.168.1.2): 56 data bytes
3289
3290     64 bytes from 192.168.1.2: icmp_seq#0 ttl64 time=0.726 ms
3291
3292     64 bytes from 192.168.1.2: icmp_seq#1 ttl64 time=0.766 ms
3293
3294     64 bytes from 192.168.1.2: icmp_seq#2 ttl64 time=0.700 ms
3295
3296     64 bytes from 192.168.1.2: icmp_seq#3 ttl64 time=0.747 ms
3297
3298     64 bytes from 192.168.1.2: icmp_seq#4 ttl64 time=0.704 ms
3299
3300     
3301
3302     --- 192.168.1.2 ping statistics ---
3303
3304     5 packets transmitted, 5 packets received, 0% packet loss
3305
3306     round-trip min/avg/max/stddev = 0.700/0.729/0.766/0.025 ms
3307
3308 You could also use the machine name instead of `192.168.1.2` if you have set up the `/etc/hosts` file.
3309
3310 #### Troubleshooting 
3311
3312 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.
3313
3314 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.
3315
3316 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.
3317
3318 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.
3319
3320 ***`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].
3321
3322 ***`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.
3323
3324 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.
3325
3326 ## Virtual Hosts 
3327
3328 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.
3329
3330 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`.
3331
3332 An alias entry for the interface `fxp0` looks like:
3333
3334     
3335
3336     ifconfig_fxp0_alias0="inet xxx.xxx.xxx.xxx netmask xxx.xxx.xxx.xxx"
3337
3338 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.
3339
3340 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`).
3341
3342 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`.
3343
3344 The following entries configure the adapter correctly for this arrangement:
3345
3346     
3347
3348      ifconfig_fxp0="inet 10.1.1.1 netmask 255.255.255.0"
3349
3350      ifconfig_fxp0_alias0="inet 10.1.1.2 netmask 255.255.255.255"
3351
3352      ifconfig_fxp0_alias1="inet 10.1.1.3 netmask 255.255.255.255"
3353
3354      ifconfig_fxp0_alias2="inet 10.1.1.4 netmask 255.255.255.255"
3355
3356      ifconfig_fxp0_alias3="inet 10.1.1.5 netmask 255.255.255.255"
3357
3358      ifconfig_fxp0_alias4="inet 202.0.75.17 netmask 255.255.255.240"
3359
3360      ifconfig_fxp0_alias5="inet 202.0.75.18 netmask 255.255.255.255"
3361
3362      ifconfig_fxp0_alias6="inet 202.0.75.19 netmask 255.255.255.255"
3363
3364      ifconfig_fxp0_alias7="inet 202.0.75.20 netmask 255.255.255.255"
3365
3366 CategoryHandbook
3367
3368 CategoryHandbook-configuration
3369
3370 ## Configuration Files 
3371
3372 ### /etc Layout 
3373
3374 There are a number of directories in which configuration information is kept. These include:
3375
3376 [[!table  data="""
3377  `/etc` | Generic system configuration information; data here is system-specific. 
3378  `/etc/defaults` | Default versions of system configuration files. 
3379  `/etc/mail` | Extra [sendmail(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=sendmail&section=8) configuration, other MTA configuration files. 
3380  `/etc/ppp` | Configuration for both user- and kernel-ppp programs. 
3381  `/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. 
3382  `/usr/local/etc` | Configuration files for installed applications. May contain per-application subdirectories. 
3383  `/usr/local/etc/rc.d` | Start/stop scripts for installed applications. 
3384  `/var/db` | Automatically generated system-specific database files, such as the package database, the locate database, and so on |
3385
3386 """]]
3387
3388 ### Hostnames 
3389
3390 #### /etc/resolv.conf 
3391
3392 `/etc/resolv.conf` dictates how DragonFly's resolver accesses the Internet Domain Name System (DNS).
3393
3394 The most common entries to `resolv.conf` are:
3395
3396 [[!table  data="""
3397  `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.
3398  `search` | Search list for hostname lookup. This is normally determined by the domain of the local hostname. 
3399  `domain` | The local domain name. |
3400
3401 """]]
3402
3403 A typical `resolv.conf`:
3404
3405     
3406
3407     search example.com
3408
3409     nameserver 147.11.1.11
3410
3411     nameserver 147.11.100.30
3412
3413  **Note:** Only one of the `search` and `domain` options should be used.
3414
3415 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.
3416
3417 #### /etc/hosts 
3418
3419 `/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.
3420
3421     
3422
3423     #
3424
3425     #
3426
3427     # Host Database
3428
3429     # This file should contain the addresses and aliases
3430
3431     # for local hosts that share this file.
3432
3433     # In the presence of the domain name service or NIS, this file may
3434
3435     # not be consulted at all; see /etc/nsswitch.conf for the resolution order.
3436
3437     #
3438
3439     #
3440
3441     ::1                     localhost localhost.my.domain myname.my.domain
3442
3443     127.0.0.1               localhost localhost.my.domain myname.my.domain
3444
3445     #
3446
3447     # Imaginary network.
3448
3449     #10.0.0.2               myname.my.domain myname
3450
3451     #10.0.0.3               myfriend.my.domain myfriend
3452
3453     #
3454
3455     # According to RFC 1918, you can use the following IP networks for
3456
3457     # private nets which will never be connected to the Internet:
3458
3459     #
3460
3461     #       10.0.0.0        -   10.255.255.255
3462
3463     #       172.16.0.0      -   172.31.255.255
3464
3465     #       192.168.0.0     -   192.168.255.255
3466
3467     #
3468
3469     # In case you want to be able to connect to the Internet, you need
3470
3471     # real official assigned numbers.  PLEASE PLEASE PLEASE do not try
3472
3473     # to invent your own network numbers but instead get one from your
3474
3475     # network provider (if any) or from the Internet Registry (ftp to
3476
3477     # rs.internic.net, directory `/templates').
3478
3479     #
3480
3481 `/etc/hosts` takes on the simple format of:
3482
3483     
3484
3485     [Internet address] [official hostname] [alias1] [alias2] ...
3486
3487 For example:
3488
3489     
3490
3491     10.0.0.1 myRealHostname.example.com myRealHostname foobar1 foobar2
3492
3493 Consult [hosts(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=hosts&section=5) for more information.
3494
3495 ### Log File Configuration 
3496
3497 #### syslog.conf 
3498
3499 `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.
3500
3501     
3502
3503     #
3504
3505     #
3506
3507     #       Spaces ARE valid field separators in this file. However,
3508
3509     #       other *nix-like systems still insist on using tabs as field
3510
3511     #       separators. If you are sharing this file between systems, you
3512
3513     #       may want to use only tabs as field separators here.
3514
3515     #       Consult the syslog.conf(5) manual page.
3516
3517     
3518 *.err;kern.debug;auth.notice;mail.crit          /dev/console
3519
3520     *.notice;kern.debug;lpr.info;mail.crit;news.err /var/log/messages
3521
3522     security.*                                      /var/log/security
3523
3524     mail.info                                       /var/log/maillog
3525
3526     lpr.info                                        /var/log/lpd-errs
3527
3528     cron.*                                          /var/log/cron
3529
3530     
3531 *.err                                           root
3532
3533     *.notice;news.err                               root
3534
3535     *.alert                                         root
3536
3537     *.emerg                                         *
3538
3539     # uncomment this to log all writes to /dev/console to /var/log/console.log
3540
3541     #console.info                                   /var/log/console.log
3542
3543     # uncomment this to enable logging of all log messages to /var/log/all.log
3544
3545     #*.*                                            /var/log/all.log
3546
3547     # uncomment this to enable logging to a remote log host named loghost
3548
3549     #*.*                                            @loghost
3550
3551     # uncomment these if you're running inn
3552
3553     # news.crit                                     /var/log/news/news.crit
3554
3555     # news.err                                      /var/log/news/news.err
3556
3557     # news.notice                                   /var/log/news/news.notice
3558
3559     !startslip
3560
3561     
3562 *.*                                             /var/log/slip.log
3563
3564     !ppp
3565
3566     
3567 *.*                                             /var/log/ppp.log
3568
3569 Consult the [syslog.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=syslog.conf&section=5) manual page for more information.
3570
3571 #### newsyslog.conf 
3572
3573 `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.
3574
3575 `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.
3576
3577     
3578
3579     # configuration file for newsyslog
3580
3581     #
3582
3583     #
3584
3585     # filename          [owner:group]    mode count size when [ZB] [/pid_file] [sig_num]
3586
3587     /var/log/cron                           600  3     100  *     Z
3588
3589     /var/log/amd.log                        644  7     100  *     Z
3590
3591     /var/log/kerberos.log                   644  7     100  *     Z
3592
3593     /var/log/lpd-errs                       644  7     100  *     Z
3594
3595     /var/log/maillog                        644  7     *    @T00  Z
3596
3597     /var/log/sendmail.st                    644  10    *    168   B
3598
3599     /var/log/messages                       644  5     100  *     Z
3600
3601     /var/log/all.log                        600  7     *    @T00  Z
3602
3603     /var/log/slip.log                       600  3     100  *     Z
3604
3605     /var/log/ppp.log                        600  3     100  *     Z
3606
3607     /var/log/security                       600  10    100  *     Z
3608
3609     /var/log/wtmp                           644  3     *    @01T05 B
3610
3611     /var/log/daily.log                      640  7     *    @T00  Z
3612
3613     /var/log/weekly.log                     640  5     1    $W6D0 Z
3614
3615     /var/log/monthly.log                    640  12    *    $M1D0 Z
3616
3617     /var/log/console.log                    640  5     100  *     Z
3618
3619 Consult the [newsyslog(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=newsyslog&section=8) manual page for more information.
3620
3621 ### sysctl.conf 
3622
3623 `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.
3624
3625 A sample `sysctl.conf` turning off logging of fatal signal exits and letting Linux programs know they are really running under DragonFly:
3626
3627     
3628
3629     kern.logsigexit=0       # Do not log fatal signal exits (e.g. sig 11)
3630
3631     compat.linux.osname=DragonFly
3632
3633     compat.linux.osrelease=4.3-STABLE
3634
3635     
3636     
3637     
3638     
3639     
3640 ## Tuning with sysctl 
3641
3642 [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).
3643
3644 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.
3645
3646 To view all readable variables:
3647
3648     
3649
3650     % sysctl -a
3651
3652 To read a particular variable, for example, `kern.maxproc`:
3653
3654     
3655
3656     % sysctl kern.maxproc
3657
3658     kern.maxproc: 1044
3659
3660 To set a particular variable, use the intuitive `***variable***`=`***value***` syntax:
3661
3662     
3663
3664     # sysctl kern.maxfiles=5000
3665
3666     kern.maxfiles: 2088 -< 5000
3667
3668 Settings of sysctl variables are usually either strings, numbers, or booleans (a boolean being `1` for yes or a `0` for no).
3669
3670 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].
3671
3672 ### sysctl(8) Read-only 
3673
3674 ***Contributed by Tom Rhodes. ***
3675
3676 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.
3677
3678 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:
3679
3680     
3681
3682     cbb0: Could not map register memory
3683
3684     device_probe_and_attach: cbb0 attach returned 12
3685
3686 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.
3687
3688 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.
3689
3690 ## Tuning Disks 
3691
3692 ### Sysctl Variables 
3693
3694 #### `vfs.vmiodirenable` 
3695
3696 The `vfs.vmiodirenable` sysctl variable may be set to either 0 (off) or 1 (on); it is 1 by default. This variable controls how directories are cached by the system. Most directories are small, using just a single fragment (typically 1 K) in the file system and less (typically 512 bytes) in the buffer cache. With this variable turned off (to 0), the buffer cache will only cache a fixed number of directories even if ou have a huge amount of memory. When turned on (to 1), this sysctl allows the buffer cache to use the VM Page Cache to cache the directories, making all the memory available for caching directories. However, the minimum in-core memory used to cache a directory is the physical page size (typically 4 K) rather than 512  bytes. We recommend keeping this option on if you are running any services which manipulate large numbers of files. Such services can include web caches, large mail systems, and news systems. Keeping this option on will generally not reduce performance even with the wasted memory but you should experiment to find out.
3697
3698 #### `vfs.write_behind` 
3699
3700 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.
3701
3702 #### `vfs.hirunningspace` 
3703
3704 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.
3705
3706 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.
3707
3708 #### `vm.swap_idle_enabled` 
3709
3710 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.
3711
3712 #### `hw.ata.wc` 
3713
3714 IDE drives lie about when a write completes. With IDE write caching turned on, IDE hard drives not only write data to disk out of order, but will sometimes delay writing some blocks indefinitely when under heavy disk loads. A crash or power failure may cause serious file system corruption. Turning off write caching will remove the danger of this data loss, but will also cause disk operations to proceed ***very slowly.*** Change this only if prepared to suffer with the disk slowdown.
3715
3716 Changing this variable must be done from the boot loader at boot time. Attempting to do it after the kernel boots will have no effect.
3717
3718 For more information, please see [ata(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=ata&section=4) manual page.
3719
3720 <!-- XXX: add some more sysctls, e.g. relating to AHCI, nata, ... -->
3721
3722 ### Soft Updates 
3723
3724 **Note** that soft updates are only available on UFS.
3725
3726 The [tunefs(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=tunefs&section=8) program can be used to fine-tune a UFS file system. This program has many different options, but for now we are only concerned with toggling Soft Updates on and off, which is done by:
3727
3728     
3729
3730     # tunefs -n enable /filesystem
3731
3732     # tunefs -n disable /filesystem
3733
3734 A filesystem cannot be modified with [tunefs(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=tunefs&section=8) while it is mounted. A good time to enable Soft Updates is before any partitions have been mounted, in single-user mode.
3735
3736  **Note:** It is possible to enable Soft Updates at filesystem creation time, through use of the `-U` option to [newfs(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=newfs&section=8).
3737
3738 Soft Updates drastically improves meta-data performance, mainly file creation and deletion, through the use of a memory cache. We recommend to use Soft Updates on all of your file systems. There are two downsides to Soft Updates that you should be aware of: First, Soft Updates guarantees filesystem consistency in the case of a crash but could very easily be several seconds (even a minute!) behind updating the physical disk. If your system crashes you may lose more work than otherwise. Secondly, Soft Updates delays the freeing of filesystem blocks. If you have a filesystem (such as the root filesystem) which is almost full, performing a major update, such as `make installworld`, can cause the filesystem to run out of space and the update to fail.
3739
3740 #### More Details about Soft Updates 
3741 <!-- XXX: consider axing this section -->
3742
3743 There are two traditional approaches to writing a file systems meta-data back to disk. (Meta-data updates are updates to non-content data like inodes or directories.)
3744
3745 Historically, the default behavior was to write out meta-data updates synchronously. If a directory had been changed, the system waited until the change was actually written to disk. The file data buffers (file contents) were passed through the buffer cache and backed up to disk later on asynchronously. The advantage of this implementation is that it operates safely. If there is a failure during an update, the meta-data are always in a consistent state. A file is either created completely or not at all. If the data blocks of a file did not find their way out of the buffer cache onto the disk by the time of the crash, [fsck(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#fsck&section8) is able to recognize this and repair the filesystem by setting the file length to 0. Additionally, the implementation is clear and simple. The disadvantage is that meta-data changes are slow. An `rm -r`, for instance, touches all the files in a directory sequentially, but each directory change (deletion of a file) will be written synchronously to the disk. This includes updates to the directory itself, to the inode table, and possibly to indirect blocks allocated by the file. Similar considerations apply for unrolling large hierarchies (`tar -x`).
3746
3747 The second case is asynchronous meta-data updates. This is the default for Linux/ext2fs and `mount -o async` for *BSD ufs. All meta-data updates are simply being passed through the buffer cache too, that is, they will be intermixed with the updates of the file content data. The advantage of this implementation is there is no need to wait until each meta-data update has been written to disk, so all operations which cause huge amounts of meta-data updates work much faster than in the synchronous case. Also, the implementation is still clear and simple, so there is a low risk for bugs creeping into the code. The disadvantage is that there is no guarantee at all for a consistent state of the filesystem. If there is a failure during an operation that updated large amounts of meta-data (like a power failure, or someone pressing the reset button), the filesystem will be left in an unpredictable state. There is no opportunity to examine the state of the filesystem when the system comes up again; the data blocks of a file could already have been written to the disk while the updates of the inode table or the associated directory were not. It is actually impossible to implement a `fsck` which is able to clean up the resulting chaos (because the necessary information is not available on the disk). If the filesystem has been damaged beyond repair, the only choice is to use [newfs(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#newfs&section8) on it and restore it from backup.
3748
3749 The usual solution for this problem was to implement ***dirty region logging***, which is also referred to as ***journaling***, although that term is not used consistently and is occasionally applied to other forms of transaction logging as well. Meta-data updates are still written synchronously, but only into a small region of the disk. Later on they will be moved to their proper location. Because the logging area is a small, contiguous region on the disk, there are no long distances for the disk heads to move, even during heavy operations, so these operations are quicker than synchronous updates. Additionally the complexity of the implementation is fairly limited, so the risk of bugs being present is low. A disadvantage is that all meta-data are written twice (once into the logging region and once to the proper location) so for normal work, a performance ***pessimization*** might result. On the other hand, in case of a crash, all pending meta-data operations can be quickly either rolled-back or completed from the logging area after the system comes up again, resulting in a fast filesystem startup.
3750
3751 Kirk McKusick, the developer of Berkeley FFS, solved this problem with Soft Updates: all pending meta-data updates are kept in memory and written out to disk in a sorted sequence (***ordered meta-data updates***). This has the effect that, in case of heavy meta-data operations, later updates to an item ***catch*** the earlier ones if the earlier ones are still in memory and have not already been written to disk. So all operations on, say, a directory are generally performed in memory before the update is written to disk (the data blocks are sorted according to their position so that they will not be on the disk ahead of their meta-data). If the system crashes, this causes an implicit ***log rewind***: all operations which did not find their way to the disk appear as if they had never happened. A consistent filesystem state is maintained that appears to be the one of 30 to 60 seconds earlier. The algorithm used guarantees that all resources in use are marked as such in their appropriate bitmaps: blocks and inodes. After a crash, the only resource allocation error that occurs is that resources are marked as ***used*** which are actually ***free***. [fsck(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#fsck&section8) recognizes this situation, and frees the resources that are no longer used. It is safe to ignore the dirty state of the filesystem after a crash by forcibly mounting it with `mount -f`. In order to free resources that may be unused, [fsck(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=fsck&section=8) needs to be run at a later time.
3752
3753 The advantage is that meta-data operations are nearly as fast as asynchronous updates (i.e. faster than with ***logging***, which has to write the meta-data twice). The disadvantages are the complexity of the code (implying a higher risk for bugs in an area that is highly sensitive regarding loss of user data), and a higher memory consumption. Additionally there are some idiosyncrasies one has to get used to. After a crash, the state of the filesystem appears to be somewhat ***older***. In situations where the standard synchronous approach would have caused some zero-length files to remain after the `fsck`, these files do not exist at all with a Soft Updates filesystem because neither the meta-data nor the file contents have ever been written to disk. Disk space is not released until the updates have been written to disk, which may take place some time after running `rm`. This may cause problems when installing large amounts of data on a filesystem that does not have enough free space to hold all the files twice.
3754
3755 ## Tuning Kernel Limits 
3756
3757 ### File/Process Limits 
3758
3759 #### `kern.maxfiles` 
3760
3761 <!-- XXX: revise this section; someone who knows about it -->
3762
3763 `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.
3764
3765 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.
3766
3767 `kern.maxfile`'s default value is dictated by the `MAXUSERS` option in your kernel configuration file. `kern.maxfiles` grows proportionally to the value of `MAXUSERS`. When compiling a custom kernel, it is a good idea to set this kernel configuration option according to the uses of your system. From this number, the kernel is given most of its pre-defined limits. Even though a production machine may not actually have 256 users connected at once, the resources needed may be similar to a high-scale web server.
3768
3769  **Note:** Setting `MAXUSERS` to `0` in your kernel configuration file will choose a reasonable default value based on the amount of RAM present in your system. It is set to 0 in the default GENERIC kernel.
3770
3771 #### `kern.ipc.somaxconn` 
3772
3773 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.
3774
3775 ### Network Limits 
3776
3777 The `NMBCLUSTERS` kernel configuration option dictates the amount of network Mbufs available to the system. 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. We recommend values between 4096 and 32768 for machines with greater amounts of memory. Under no circumstances should you specify an arbitrarily high value for this parameter as it could lead to a boot time crash. 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.
3778
3779 <!-- XXX: mention kern.ipc.mbufs sysctl -->
3780
3781 For busy servers that make extensive use of the [sendfile(2)](http://leaf.dragonflybsd.org/cgi/web-man?command=sendfile&section=2) system call, it may be necessary to increase the number of [sendfile(2)](http://leaf.dragonflybsd.org/cgi/web-man?command=sendfile&section=2) buffers via the `NSFBUFS` kernel configuration option or by setting its value in `/boot/loader.conf` (see [loader(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=loader&section=8) for details). A common indicator that this parameter needs to be adjusted is when processes are seen in the `sfbufa` state. The sysctl variable `kern.ipc.nsfbufs` is a read-only glimpse at the kernel configured variable. This parameter nominally scales with `kern.maxusers`, however it may be necessary to tune accordingly.
3782
3783  **Important:** Even though a socket has been marked as non-blocking, calling [sendfile(2)](http://leaf.dragonflybsd.org/cgi/web-man?command=sendfile&section=2) on the non-blocking socket may result in the [sendfile(2)](http://leaf.dragonflybsd.org/cgi/web-man?command=sendfile&section=2) call blocking until enough `struct sf_buf`'s are made available.
3784
3785 #### `net.inet.ip.portrange.*` 
3786
3787 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.
3788
3789 #### TCP Bandwidth Delay Product 
3790 <!-- XXX: Revise this stuff, I'm not familiar with it -->
3791
3792 The TCP Bandwidth Delay Product Limiting is similar to TCP/Vegas in NetBSD. It can be enabled by setting `net.inet.tcp.inflight_enable` sysctl variable to `1`. 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.
3793
3794 This feature is useful if you are serving data over modems, Gigabit Ethernet, or even high speed WAN links (or any other link with a high bandwidth delay product), especially if you are also using window scaling or have configured a large send window. If you enable this option, you should also be sure to set `net.inet.tcp.inflight_debug` to `0` (disable debugging), and for production use setting `net.inet.tcp.inflight_min` to at least `6144`&nbs