13 The DragonFly newcomer will find that the first section of this book guides the user through the DragonFly installation process and gently introduces the concepts and conventions that underpin UNIX®. Working through this section requires little more than the desire to explore, and the ability to take on broad new concepts as they are introduced.
17 Once you have travelled this far, the second, far larger, section of the Handbook is a comprehensive reference to all manner of topics of interest to DragonFly system administrators. Some of these chapters may recommend that you do some prior reading, and this is noted in the synopsis at the beginning of each chapter.
21 For a list of additional sources of information, please see [Appendix B](bibliography.html).
24 <!-- Cut out of "Organization of This Book" -->
28 ## Conventions used in this book
32 To provide a consistent and easy to read text, several conventions are followed throughout the book.
36 ### Typographic Conventions
42 :: An ***italic*** font is used for filenames, URLs, emphasized text, and the first usage of technical terms.
48 :: A `monospaced` font is used for error messages, commands, environment variables, names of ports, hostnames, user names, group names, device names, variables, and code fragments.
54 :: A **bold** font is used for applications, commands, and keys.
62 Keys are shown in **bold** to stand out from other text. Key combinations that are meant to be typed simultaneously are shown with **+** between the keys, such as:
66 **Ctrl** + **Alt** + **Del**
70 Meaning the user should type the **Ctrl** , **Alt** ,and **Del** keys at the same time.
74 Keys that are meant to be typed in sequence will be separated with commas, for example:
78 **Ctrl** + **X** , **Ctrl** + **S**
82 Would mean that the user is expected to type the **Ctrl** and **X** keys simultaneously and then to type the **Ctrl** and **S** keys simultaneously.
90 Examples starting with # indicate a command that must be invoked as the superuser in DragonFly. You can login as `root` to type the command, or login as your normal account and use [su(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=su§ion1) to gain superuser privileges.
96 # dd if=kern.flp of=/dev/fd0
102 Examples starting with % indicate a command that should be invoked from a normal user account. Unless otherwise noted, C-shell syntax is used for setting environment variables and other shell commands.
114 Examples starting with `E:\>` indicate a MS-DOS® command. Unless otherwise noted, these commands may be executed from a ***Command Prompt*** window in a modern Microsoft® Windows® environment.
120 E:\> tools\fdimage floppies\kern.flp A:
130 The book you are holding represents the efforts of many hundreds of people around the world. Whether they sent in fixes for typos, or submitted complete chapters, all the contributions have been useful.
134 The DragonFly Handbook was originally built from an edition of the FreeBSD Handbook. The FreeBSD Handbook was created by the collective hard work of hundreds of people, and the DragonFly Documentation Team appreciates all their labor.
149 This part of the DragonFly Handbook is for users and administrators who are new to DragonFly. These chapters:
154 * Introduce you to DragonFly.
157 * Guide you through the installation process.
160 * Teach you UNIX® basics and fundamentals.
163 * Show you how to install the wealth of third party applications available for DragonFly.
166 * Introduce you to X, the UNIX windowing system, and detail how to configure a desktop environment that makes you more productive.
170 We have tried to keep the number of forward references in the text to a minimum so that you can read this section of the Handbook from front to back with the minimum page flipping required.
180 ## Chapter 1 Introduction
182 ***Restructured, reorganized, and parts rewritten by Jim Mock. ***
190 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.
194 After reading this chapter, you will know:
199 * How DragonFly relates to other computer operating systems.
202 * The history of the DragonFly Project.
205 * The goals of the DragonFly Project.
208 * The basics of the DragonFly open-source development model.
211 * And of course: where the name ***DragonFly*** comes from.
222 # 1.2 Welcome to DragonFly!
226 DragonFly is a 4.4BSD-Lite based operating system for Intel (x86) and amd64 (x86_64). You can also read about [the history of DragonFly](history.html), or the [ current release](history.html#RELNOTES).
230 ## 1.2.1 What Can DragonFly Do?
234 <!-- Cutout of "features". This is outdated bullshit -->
238 DragonFly is based on the 4.4BSD-Lite release from Computer Systems Research Group (CSRG) at the University of California at Berkeley, along with later development of FreeBSD by the FreeBSD Project. 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. As many of the commercial giants struggle to field PC operating systems with such features, performance and reliability, DragonFly can offer them ***now***!
243 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 then 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 centers and universities around the world, often available at little to no cost. Commercial applications are also available and appearing in greater numbers every day.
248 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:
252 The robust TCP/IP networking built into DragonFly makes it an ideal platform for a variety of Internet services such as:
255 * World Wide Web servers (standard or secure [SSL])
256 * Firewalls and NAT (***IP masquerading***) gateways
257 * Electronic Mail servers
258 * USENET News or Bulletin Board Systems
263 With DragonFly, you can easily start out small with an inexpensive 386 class PC and upgrade all the way up to a quad-processor Xeon with RAID storage as your enterprise grows.
267 * ***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!
270 * ***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.
273 * ***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.
276 * ***X Window workstation:*** DragonFly is a fine choice for an inexpensive X terminal solution, either using the freely available XFree86™ or X.org servers or one of the excellent commercial servers provided by [Xi Graphics](http://www.xig.com). 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.
279 * ***Software Development:*** The basic DragonFly system comes with a full complement of development tools including the renowned GNU C/C++ compiler and debugger.
281 DragonFly is available via anonymous FTP or GIT. Please see [Appendix A](mirrors.html) for more information about obtaining DragonFly.
290 # About the DragonFly Project
294 The following section provides some background information on the project, including a brief history, project goals, and the development model of the project.
297 ## A Brief History of DragonFly
301 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.
305 ## DragonFly Project Goals
307 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.
311 ## The DragonFly Development Model
313 ***Written by Justin Sherrill. ***
315 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.
318 Source for DragonFly is kept in [git](http://www.git.org/) which is 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.
322 ## The Current DragonFly Release
324 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.
331 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.
342 ## Chapter 2 Installation from CD
344 This document describes the installation of DragonFly BSD. This process uses a bootable DragonFly CD, usually referred to as a 'live CD'. This CD is available at one of the current mirrors, which distribute the images by various protocols. The authorative list can be found at the [DragonFly website](http://www.dragonflybsd.org/download/).
346 <!-- XXX: add stuff about usb stick -->
357 Upon booting, you see the following screen:
359 <!-- XXX: insert image -->
362 As you can see, it gives you the option of logging in as `root` to run the live CD and play around or logging in as `installer` to install DragonFly to your hard drive.
364 Log in as `installer`. You will then see the following screen:
366 <!-- XXX: insert image -->
370 ## Set up Disk for Installation
372 Note the warning to backup important data. Things can always go wrong and if, for example, you have another partition with important files, a mistype or other error might lose all the information on that partition. Assuming this is done, or that you aren't worried about other data on the machine, again, select install DragonFly BSD and you will be taken to the next screen:
374 <!-- XXX: insert image-->
376 If you have multiple disks installed, chose one where you want to install DragonFly. We chose `ad0` here.
378 <!-- XXX: insert image-->
380 After selecting the disk we need to decide how much of the disk we want to use. We choose to use the entire disk and see the next screen. Now we can chose between the two file systems on DragonFly. HAMMER is the brand-new file system with a big number of features like snapshots, history tracking, mirroring etc. UFS is the old BSD file system.
381 <!-- XXX: mention stuf about UFS+HAMMER being the default setup, and why. -->
383 <!-- XXX: insert image -->
385 We select HAMMER and see now the following screen:
387 <!-- XXX: insert image -->
389 The screen (shown above) gives the default partition scheme for this drive. As the screen says, the * indicates that it will use remainder of the disk. If you chose HAMMER as your file system there is no need to change the default settings. One swap partition is created and the remaining space is assigned to the root partition. The installer will automatically add sub-partitions (called Pseudo File Systems (PFS) in HAMMER) for /home, /usr, /var, /var/crash, /var/tmp and /tmp for you. If you want to get more information about HAMMER, have a look in the man page.
397 The following steps show how DragonFly can be installed to your hard disk:
401 Depending on your hardware installing DragonFly will take some time. Once installation is complete, you are given an option to install bootblocks. Note that if you are installing bootblocks and the DragonFly installation is above the 1024th cylinder (approximately 8 gigs) accept the default of having packet mode selected:
405 Next, we are given an option to configure the system or reboot:
413 ## Set up your system
416 The following menu of the installer allows you to configure your previously installed system.
420 This includes setting a password for your `root` account:
424 Be sure to select the correct keyboard map for your system:
428 Configure the hostname is done like that:
434 To perform your daily work, it is recommended to work as an unprivileged user. Use the following screen to create such an account. If you want to allow your user to use [su(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=su§ion1), also add him to the `wheel` group:
438 ### Configure the Network
440 The next screen allows you to setup your network. The installed card seen here is an Intel Ethernet 1000 powered by [em(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=em§ion4):
445 After finishing your configuration you can escape into a live shell or reboot the system into your installation.
460 ## Chapter 3 UNIX Basics
462 ***Rewritten by Chris Shumway. ***
470 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.
474 After reading this chapter, you will know:
479 * How to use the ***virtual consoles*** of DragonFly.
482 * How UNIX file permissions work along with understanding file flags in DragonFly.
485 * The default DragonFly file system layout.
488 * The DragonFly disk organization.
491 * How to mount and unmount file systems.
494 * What processes, daemons, and signals are.
497 * What a shell is, and how to change your default login environment.
500 * How to use basic text editors.
503 * What devices and device nodes are.
506 * What binary format is used under DragonFly.
509 * How to read manual pages for more information.
521 ## Virtual Consoles and Terminals
524 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.
526 <!-- XXX: also mention vesa.ko and other modes for the vt, but maybe somewhere else -->
530 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:
533 Additional ABI support:.
535 Local package initialization:.
536 Additional TCP options:.
538 Wed Feb 18 17:53:48 GMT 2009
540 DragonFly/i386 (Amnesiac) (ttyv0)
545 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:
548 DragonFly/i386 (Amnesiac) (ttyv0)
551 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:
557 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.
560 ### Logging into DragonFly
562 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.
564 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:
568 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>:
576 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.
578 ### Multiple Consoles
580 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.
583 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.
586 ### The /etc/ttys File
588 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.
591 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`:
594 # name getty type status comments
596 ttyv0 "/usr/libexec/getty Pc" cons25 on secure
598 ttyv1 "/usr/libexec/getty Pc" cons25 on secure
599 ttyv2 "/usr/libexec/getty Pc" cons25 on secure
600 ttyv3 "/usr/libexec/getty Pc" cons25 on secure
601 ttyv4 "/usr/libexec/getty Pc" cons25 on secure
602 ttyv5 "/usr/libexec/getty Pc" cons25 on secure
603 ttyv6 "/usr/libexec/getty Pc" cons25 on secure
604 ttyv7 "/usr/libexec/getty Pc" cons25 on secure
605 ttyv8 "/usr/pkg/xorg/bin/xdm -nodaemon" xterm off secure
608 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§ion5) manual page.
612 ### Single User Mode Console
614 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`:
618 # name getty type status comments
620 # If console is marked "insecure", then init will ask for the root password
621 # when going to single-user mode.
622 console none unknown off secure
628 **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.
637 <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.
638 [ (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.
639 [ (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§ion4), [atkbd(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=atkbd§ion=4), [vidcontrol(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=vidcontrol§ion=1) and [kbdcontrol(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=kbdcontrol§ion=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. |
649 CategoryHandbook-basics
655 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.
657 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:
662 |<tablestyle="width:100%"> Value | Permission | Directory Listing
663 <tablestyle="width:100%"> 0 | No read, no write, no execute | `---`
664 1 | No read, no write, execute | `--x`
665 2 | No read, write, no execute | `-w-`
666 3 | No read, write, execute | `-wx`
667 4 | Read, no write, no execute | `r--`
668 5 | Read, no write, execute | `r-x`
669 6 | Read, write, no execute | `rw-`
670 7 | Read, write, execute | `rwx` |
674 You can use the `-l` command line argument to [ls(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ls§ion1) 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:
680 -rw-r--r-- 1 root wheel 512 Sep 5 12:31 myfile
681 -rw-r--r-- 1 root wheel 512 Sep 5 12:31 otherfile
682 -rw-r--r-- 1 root wheel 7680 Sep 5 12:31 email.txt
685 Here is how the first column of `ls -l` is broken up:
689 <!-- XXX: Check all these http:// links to see if they are broken -->
691 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.
695 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.
699 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).
701 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§ion1) manual page.
705 ### Symbolic Permissions
709 ***Contributed by Tom Rhodes.***
713 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:
718 <tablestyle="width:100%"> Option | Letter | Represents
719 <tablestyle="width:100%"> (who) | u | User
720 (who) | g | Group owner
722 (who) | a | All (***world***)
723 (action) | + | Adding permissions
724 (action) | - | Removing permissions
725 (action) | = | Explicitly set permissions
726 (permissions) | r | Read
727 (permissions) | w | Write
728 (permissions) | x | Execute
729 (permissions) | t | Sticky bit
730 (permissions) | s | Set UID or GID |
734 These values are used with the [chmod(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=chmod&section1) command just like before, but with letters. For an example, you could use the following command to block other users from accessing `FILE`:
746 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:
752 % chmod go-w,a+x FILE
758 ### DragonFly File Flags
762 ***Contributed by Tom Rhodes.***
766 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&section1) utility, using a simple interface. For example, to enable the system undeletable flag on the file `file1`, issue the following command:
772 # chflags sunlink file1
778 And to disable the system undeletable flag, simply issue the previous command with ***no*** in front of the `sunlink`. Observe:
784 # chflags nosunlink file1
790 To view the flags of this file, use the [ls(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ls&section1) with the `-lo` flags:
802 The output should look like the following:
808 -rw-r--r-- 1 trhodes trhodes sunlnk 0 Mar 1 05:54 file1
814 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§ion1) and [chflags(2)](http://leaf.dragonflybsd.org/cgi/web-man?command=chflags§ion=2) manual pages for more information.
819 ## Directory Structure
823 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.
827 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§ion8) unless they contain the `noauto` option. Details can be found in [ this section](mount-unmount.html#DISKS-FSTAB).
831 A complete description of the file system hierarchy is available in [hier(7)](http://leaf.dragonflybsd.org/cgi/web-man?command=hier§ion7). For now, a brief overview of the most common directories will suffice.
836 <tablestyle="width:100%">Directory | Description
837 <tablestyle="width:100%"> `/` | Root directory of the file system.
838 `/bin/` | User utilities fundamental to both single-user and multi-user environments.
839 `/boot/` | Programs and configuration files used during operating system bootstrap.
840 `/boot/defaults/` | Default bootstrapping configuration files; see [loader.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=loader.conf§ion5).
841 `/dev/` | Device nodes; see [intro(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=intro§ion4).
842 `/etc/` | System configuration files and scripts.
843 `/etc/defaults/` | Default system configuration files; see [rc(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rc§ion8).
844 `/etc/mail/` | Configuration files for mail transport agents such as [sendmail(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=sendmail§ion8).
845 `/etc/namedb/` | `named` configuration files; see [named(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=named§ion8).
846 `/etc/periodic/` | Scripts that are run daily, weekly, and monthly, via [cron(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=cron§ion8); see [periodic(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=periodic§ion=8).
847 `/etc/ppp/` | `ppp` configuration files; see [ppp(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=ppp§ion8).
848 `/mnt/` | Empty directory commonly used by system administrators as a temporary mount point.
849 `/proc/` | Process file system; see [procfs(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=procfs§ion5), [mount_procfs(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=mount_procfs§ion=8).
850 `/root/` | Home directory for the `root` account.
851 `/sbin/` | System programs and administration utilities fundamental to both single-user and multi-user environments.
852 `/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§ion8).
853 `/usr/` | The majority of user utilities and applications.
854 `/usr/bin/` | Common utilities, programming tools, and applications.
855 `/usr/include/` | Standard C include files.
856 `/usr/lib/` | Archive libraries.
857 `/usr/libdata/` | Miscellaneous utility data files.
858 `/usr/libexec/` | System daemons & system utilities (executed by other programs).
859 `/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§ion7) for `/usr` should be used. An exceptions is the man directory, which is directly under `/usr/local` rather than under `/usr/local/share`.
860 `/usr/obj/` | Architecture-specific target tree produced by building the `/usr/src` tree.
861 `/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`.
862 `/usr/pkg/xorg/` | Xorg distribution executables, libraries, etc (optional).
863 `/usr/pkgsrc` | The pkgsrc tree for installing packages (optional).
864 `/usr/sbin/` | System daemons & system utilities (executed by users).
865 `/usr/share/` | Architecture-independent files.
866 `/usr/src/` | BSD and/or local source files.
867 `/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§ion8).
868 `/var/log/` | Miscellaneous system log files.
869 `/var/mail/` | User mailbox files.
870 `/var/spool/` | Miscellaneous printer and mail system spooling directories.
871 `/var/tmp/` | Temporary files. The files are usually preserved across a system reboot, unless `/var` is a memory-based file system.
872 `/var/yp` | NIS maps. |
883 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.
887 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.
891 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`.
895 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.
899 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 `\`.
902 DragonFly does not use drive letters, or other drive names in the path. You would not write `c:/foo/bar/readme.txt` on DragonFly.
906 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.
910 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`).
914 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:
921 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:
928 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.
932 If `B` had been mounted on `A2` then the diagram would look like this:
939 and the paths would be `/A2/B1` and `/A2/B2` respectively.
943 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:
950 Or `C` could be mounted directly on to the `A` file system, under the `A1` directory:
957 If you are familiar with MS-DOS, this is similar, although not identical, to the `join` command.
963 ### Choosing File System Layout
967 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.
971 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.
975 **Benefits of Multiple File Systems**
980 * 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.
983 * 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.
986 * 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.
990 **Benefit of a Single File System**
995 * 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&section8) command makes it possible to increase the size of a UFS file system on the fly.
996 <!-- XXX: what about hammer? -->
1001 ### Disk Slices, Partitions and local UNIX file systems
1003 Here we describe how disks are subdivided.
1005 <!-- XXX: mention serno stuff -->
1009 A disk can be subdivided in slices.
1011 Slices are named `s0`, `s1` and so on.
1013 For example the disk `ad6` can contain the slice `ad6s3`.
1015 DragonFly support two schemes for slices, MBR and GPT, either of them will manage all slices on a disk:
1018 * MBR: set up using [fdisk(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=fdisk&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.
1021 * GPT: set up using [gpt(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=gpt&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&section=8).
1027 Partitions are contained in slices.
1029 Partitions are named `a`, `b` and so on.
1031 DragonFly support 16 partitions per slice, that is `a` through `p`.
1033 For example the partition `ad6s3a` is contained in the slice `ad6s3`.
1035 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):
1038 * [disklabel32(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel&section8): 32 bit disk label which can use slices with size up to 2 TB.
1041 * [disklabel64(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel64&section8): 64 bit disk label which can use very large slices: size up to 16 million TB.
1044 #### Local UNIX file systems
1046 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.
1050 DragonFly support two local UNIX file systems, UFS and HAMMER:
1053 * UFS: The classical BSD UNIX file system, see [ffs(5)](http://leaf.dragonflybsd.org/cgi/web-man?command#ffs&section5), it supports size up to 2 TB.
1056 * [HAMMER(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=HAMMER&section5): A new file system, as of DragonFly 2.0, with many advanced features. HAMMER file system support size up to 1 million TB.
1060 #### Typical disk layout
1062 From the above we see the following typical disk layout scenarios:
1065 * 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.
1068 * 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.
1071 * 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&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&section=8).
1079 [HAMMER(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=HAMMER&section5)
1081 is a rather new file system, under active development.
1083 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 .
1085 All major features except the mirroring are quite well tested as-of the 2.2.1 release.
1087 You should evaluate if HAMMER is suitable for your needs.
1088 <!-- XXX: mention disk and memory requirements for efficient hammer use -->
1091 Examples of ongoing development includes:
1094 * 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&section8) jobs for this yourself, see [hammer(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=hammer&section=8).
1097 * Multi master mirroring. For now only one mirror master is supported, but multiple mirror targets, called slaves, are already supported.
1100 * Support for shrinking existing HAMMER file systems. The HAMMER design is prepared for this, utility just have to be written to support it.
1101 <!-- XXX: is this still accurate? Do we really want to mention it here? -->
1104 #### HAMMER Features
1106 [HAMMER(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=HAMMER&section5) has several advanced features not found in UFS:
1109 * Large file systems: Up to 1 million TB, also called 1 Exabyte is supported.
1112 * 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.
1115 * 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&section=8). The HAMMER design is also prepared for removing volumes, utilities just have to be written to support it.
1118 * 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.
1121 * 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&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&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&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&section=5).
1124 * 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.
1127 * 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.
1131 More info on HAMMER can be found [here](http://www.dragonflybsd.org/hammer/index.shtml).
1135 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.
1137 <!-- XXX: mention swapcache, and also how to configure and use it (somewhere else, probably) -->
1145 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.
1149 Assuming that disk `ad6` is installed, we could set it up using [fdisk(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=fdisk&section8) and disklabel(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel&section8) or [gpt(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=gpt&section8) and
1150 [disklabel64(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel64&section8).
1152 In this example we choose [gpt(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=gpt&section=8) & [disklabel64(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel64&section=8).
1155 <!-- XXX: mention that disklabel64 is default now -->
1178 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.
1184 # disklabel64 -rw ad6s1 auto
1186 # disklabel64 -e ad6s1 # edit label to add partitions as needed
1193 <!-- XXX: what is all this fuzz about dangerously dedicated? -->
1196 For [disklabel(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel&section8) labels some partitions have certain conventions associated with them.
1201 <tablestyle="width:100%"> Partition | Convention
1202 <tablestyle="width:100%"> `a` | Normally contains the root file system
1203 `b` | Normally contains swap space
1204 `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.
1205 `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`. |
1209 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.
1213 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.
1215 <!-- XXX: gpt allows for way more than 4 partitions... let's remove this stuff above -->
1217 ***Dangerously dedicated*** physical drives are accessed as slice 0.
1221 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.
1225 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).
1227 <!-- XXX: here would probably be the right place to talk about serno -->
1229 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).
1231 <!-- XXX: later talk also about devfs, definitely not here though. also, devfs rules -->
1233 [Example 3-2](disk-organization.html#BASICS-CONCEPT-DISK-MODEL) shows a conceptual model of the disk layout that should help make things clearer.
1237 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.
1241 ***'Table 3-1. Disk Device Codes***'
1246 <tablestyle="width:100%"> Code | Meaning
1247 <tablestyle="width:100%"> `ad` | ATAPI (IDE) disk
1248 `da` | SCSI direct access disk
1249 `acd` | ATAPI (IDE) CDROM
1252 `fd` | Floppy disk |
1256 ***'Example 3-1. Sample Disk, Slice, and Partition Names***'
1261 <tablestyle="width:100%"> Name | Meaning
1262 <tablestyle="width:100%"> `ad0s1a` | The first partition (`a`) on the first slice (`s1`) on the first IDE disk (`ad0`).
1263 `da1s2e` | The fifth partition (`e`) on the second slice (`s2`) on the second SCSI disk (`da1`). |
1267 ***'Example 3-2. Conceptual Model of a Disk***'
1271 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.
1275 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.
1287 CategoryHandbook-basics
1295 ## Mounting and Unmounting File Systems
1299 The file system is best visualized as a tree, rooted at `/`.
1301 The directories, e.g. `/dev` and `/usr`, in the root directory are branches,
1303 which may have their own branches, such as `/usr/local`, and so on.
1307 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.
1311 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.
1321 During the [boot process](boot.html), file systems listed in `/etc/fstab` are automatically mounted (unless they are listed with the `noauto` option).
1325 The `/etc/fstab` file contains a list of lines of the following format:
1328 device mount-point fstype options dumpfreq passno
1330 These parameters have the following meaning:
1332 * `device`: A device name (which should exist), as explained [here](disks-naming.html).
1334 * `mount-point`: A directory (which should exist), on which to mount the file system.
1336 * `fstype`: The file system type to pass to [mount(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=mount§ion8). The default DragonFly file system is `ufs`.
1338 * `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§ion8) manual page.
1340 * `dumpfreq`: This is used by [dump(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=dump§ion8) to determine which file systems require dumping. If the field is missing, a value of zero is assumed.
1342 * `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§ion8) will attempt to check file systems in parallel if possible.
1345 Consult the [fstab(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=fstab§ion5) manual page for more information on the format of the `/etc/fstab` file and the options it contains.
1351 ### The mount Command
1355 The [mount(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=mount§ion8) command is what is ultimately used to mount file systems.
1359 In its most basic form, you use:
1365 # mount device mountpoint
1371 Or, if `mountpoint` is specified in `/etc/fstab`, just:
1383 There are plenty of options, as mentioned in the [mount(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=mount§ion8) manual page, but the most common are:
1392 * `-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.
1395 * `-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§ion8) is actually trying to do.
1398 * `-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.
1401 * `-r`: Mount the file system read-only. This is identical to using the `rdonly` argument to the `-o` option.
1404 * `-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.
1407 * `-u`: Update mount options on the file system.
1413 * `-w`: Mount the file system read-write.
1417 The `-o` option takes a comma-separated list of the options, including the following:
1422 * `nodev:` Do not interpret special devices on the file system. This is a useful security option.
1425 * `noexec`: Do not allow execution of binaries on this file system. This is also a useful security option.
1428 * `nosuid`: Do not interpret setuid or setgid flags on the file system. This is also a useful security option.
1432 ### The umount Command
1436 The [umount(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=umount§ion8) command takes, as a parameter, one of a mountpoint, a device name, or the `-a` or `-A` option.
1440 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.
1444 `-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.
1454 CategoryHandbook-basics
1465 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.
1467 <!-- XXX: talk about LWPs and threads? -->
1469 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§ion8). `init` is always the first process, so its PID is always 1. `init` is started automatically by the kernel when DragonFly starts.
1471 Two commands are particularly useful to see the processes on the system, [ps(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ps§ion1) and [top(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=top§ion=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.
1475 By default, `ps` only shows you the commands that are running and are owned by you. For example:
1483 PID TT STAT TIME COMMAND
1484 298 p0 Ss 0:01.10 tcsh
1485 7078 p0 S 2:40.88 xemacs mdoc.xsl (xemacs-21.1.14)
1486 37393 p0 I 0:03.11 xemacs freebsd.dsl (xemacs-21.1.14)
1487 48630 p0 S 2:50.89 /usr/local/lib/netscape-linux/navigator-linux-4.77.bi
1488 48730 p0 IW 0:00.00 (dns helper) (navigator-linux-)
1489 72210 p0 R+ 0:00.00 ps
1490 390 p1 Is 0:01.14 tcsh
1491 7059 p2 Is+ 1:36.18 /usr/local/bin/mutt -y
1492 6688 p3 IWs 0:00.00 tcsh
1493 10735 p4 IWs 0:00.00 tcsh
1494 20256 p5 IWs 0:00.00 tcsh
1495 262 v0 IWs 0:00.00 -tcsh (tcsh)
1496 270 v0 IW+ 0:00.00 /bin/sh /usr/X11R6/bin/startx -- -bpp 16
1497 280 v0 IW+ 0:00.00 xinit /home/nik/.xinitrc -- -bpp 16
1498 284 v0 IW 0:00.00 /bin/sh /home/nik/.xinitrc
1499 285 v0 S 0:38.45 /usr/X11R6/bin/sawfish
1503 As you can see in this example, the output from [ps(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ps§ion1) 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.
1507 [ps(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ps§ion1) 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§ion=1) to display the full command line, rather than truncating it once it gets too long to fit on the screen.
1511 The output from [top(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=top§ion1) is similar. A sample session looks like this:
1518 last pid: 72257; load averages: 0.13, 0.09, 0.03 up 0+13:38:33 22:39:10
1519 47 processes: 1 running, 46 sleeping
1520 CPU states: 12.6% user, 0.0% nice, 7.8% system, 0.0% interrupt, 79.7% idle
1521 Mem: 36M Active, 5256K Inact, 13M Wired, 6312K Cache, 15M Buf, 408K Free
1522 Swap: 256M Total, 38M Used, 217M Free, 15% Inuse
1525 PID USERNAME PRI NICE SIZE RES STATE TIME WCPU CPU COMMAND
1526 72257 nik 28 0 1960K 1044K RUN 0:00 14.86% 1.42% top
1527 7078 nik 2 0 15280K 10960K select 2:54 0.88% 0.88% xemacs-21.1.14
1528 281 nik 2 0 18636K 7112K select 5:36 0.73% 0.73% XF86_SVGA
1529 296 nik 2 0 3240K 1644K select 0:12 0.05% 0.05% xterm
1530 48630 nik 2 0 29816K 9148K select 3:18 0.00% 0.00% navigator-linu
1531 175 root 2 0 924K 252K select 1:41 0.00% 0.00% syslogd
1532 7059 nik 2 0 7260K 4644K poll 1:38 0.00% 0.00% mutt
1535 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.
1537 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§ion1). 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§ion=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.
1541 [top(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=top§ion1) automatically updates this display every two seconds; this can be changed with the `s` option.
1547 ## Daemons, Signals, and Killing Processes
1551 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.
1555 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.
1559 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.
1563 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§ion=1) or [kill(2)](http://leaf.dragonflybsd.org/cgi/web-man?command=kill§ion=2) permission will be denied. The exception to this is the `root` user, who can send signals to everyone's processes.
1567 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§ion=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.
1571 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.
1575 `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).
1579 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.
1583 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.
1587 Signals are sent using the [kill(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=kill§ion=1) command, as this example shows.
1591 **Sending a Signal to a Process**
1595 This example shows how to send a signal to [inetd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=inetd§ion=8). The `inetd` configuration file is `/etc/inetd.conf`, and `inetd` will re-read this configuration file when it is sent `SIGHUP`.
1599 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§ion=1) and [grep(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=grep§ion=1). The [grep(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=grep§ion=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§ion=8) is run as `root`, so the `ax` options must be given to [ps(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ps§ion=1).
1603 % ps -ax | grep inetd
1605 198 ?? IWs 0:00.00 inetd -wW
1609 So the [inetd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#inetd§ion8) 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§ion=1) has to find the list of running processes.
1611 2. Use [kill(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=kill§ion=1) to send the signal. Because [inetd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=inetd§ion=8) is being run by `root` you must use [su(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=su§ion=1) to become `root` first.
1619 # /bin/kill -s HUP 198
1623 In common with most UNIX® commands, [kill(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=kill§ion=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`.
1627 **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.
1631 Sending other signals is very similar, just substitute `TERM` or `KILL` in the command line as necessary.
1635 **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§ion=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§ion=1) with ***before*** you press **Return** .
1646 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`.
1650 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.
1654 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** ]`.
1658 The shell would print out `rm foo[BEEP].bar`.
1662 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.
1666 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:
1671 <tablestyle="width:100%"> Variable | Description
1672 <tablestyle="width:100%"> `USER` | Current logged in user's name.
1673 `PATH` | Colon separated list of directories to search for binaries.
1674 `DISPLAY` | Network name of the X11 display to connect to, if available.
1675 `SHELL` | The current shell.
1676 `TERM` | The name of the user's terminal. Used to determine the capabilities of the terminal.
1677 `TERMCAP` | Database entry of the terminal escape codes to perform various terminal functions.
1678 `OSTYPE` | Type of operating system. e.g., DragonFly.
1679 `MACHTYPE` | The CPU architecture that the system is running on.
1680 `EDITOR` | The user's preferred text editor.
1681 `PAGER` | The user's preferred text pager.
1682 `MANPATH` | Colon separated list of directories to search for manual pages. |
1686 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`:
1689 % setenv EDITOR /usr/pkg/bin/emacs
1692 Under Bourne shells:
1695 % export EDITOR="/usr/pkg/bin/emacs"
1699 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`.
1703 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.
1707 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.
1712 ### Changing Your Shell
1714 <!-- XXX: does chsh still exist? chpass will do, too -->
1716 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.
1719 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:
1723 % chsh -s /usr/pkg/bin/bash
1729 **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.
1733 For example, if you installed `bash` by hand and placed it into `/usr/local/bin`, you would want to:
1739 # echo "/usr/local/bin/bash" >> /etc/shells
1756 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.
1758 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.
1760 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.
1765 ## Devices and Device Nodes
1767 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`.
1769 For example, `acd0` is the first IDE CDROM drive, while `kbd0` represents the keyboard.
1771 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.
1773 The device nodes in the `/dev` directory are created and destroyed automatically on DragonFly >= 2.4, by means of the device file system (devfs).
1781 To understand why DragonFly uses the [elf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=elf&section=5) format, you must first know a little about the three currently ***dominant*** executable formats for UNIX®:
1786 * [a.out(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=a.out&section=5)
1788 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&section=5) for more details). It contains three loaded segments: .text, .data, and .bss plus a symbol table and a string table.
1793 The SVR3 object format. The header now comprises a section table, so you can have more than just .text, .data, and .bss sections.
1796 * [elf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=elf&section=5)
1798 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&section=1) for more information. DragonFly runs ELF.
1802 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.
1804 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.
1806 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.
1808 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.
1812 <!-- XXX: do we really need all this bullshit about file formats? -->
1815 ## For More Information
1819 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:
1823 `command` is the name of the command you wish to learn about. For example, to learn more about `ls` command type:
1827 The online manual is divided up into numbered sections:
1831 1. System calls and error numbers.
1832 1. Functions in the C libraries.
1835 1. Games and other diversions.
1836 1. Miscellaneous information.
1837 1. System maintenance and operation commands.
1838 1. Kernel internals.
1842 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:
1848 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§ion=1) refers to the `chmod` user command and [chmod(2)](http://leaf.dragonflybsd.org/cgi/web-man?command=chmod§ion=2) refers to the system call.
1850 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:
1857 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.
1859 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:
1870 which does the same thing.
1876 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§ion=1) command, simply type:
1881 For a brief introduction, type `h`. For a quick command reference, type `?`.
1887 ## Chapter 4 Installing Applications using NetBSD's pkgsrc framework
1890 <!-- XXX: possibly also mention pkgin and other fancy stuff. Or at least pkg_radd if it's not mentioned already -->
1894 ## Overview of Software Installation
1896 If you have used a UNIX® system before you will know that the typical procedure for installing third party software goes something like this:
1899 1. Download the software, which might be distributed in source code format, or as a binary.
1901 1. Unpack the software from its distribution format (typically a tarball compressed with [compress(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=compress§ion1), [gzip(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=gzip§ion=1), or [bzip2(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=bzip2§ion=1)).
1903 1. Locate the documentation (perhaps an `INSTALL` or `README` file, or some files in a `doc/` subdirectory) and read up on how to install the software.
1905 1. If the software was distributed in source format, compile it. This may involve editing a `Makefile`, or running a `configure` script, and other work.
1907 1. Test and install the software.
1910 And that is only if everything goes well. If you are installing a software package that was not deliberately ported to DragonFly you may even have to go in and edit the code to make it work properly. Should you want to, you can continue to install software the ***traditional*** way with DragonFly. However, DragonFly provides technology from NetBSD, which can save you a lot of effort: pkgsrc. At the time of writing, over 8,000 third party applications have been made available in this way.
1913 For any given application, the DragonFly Binary package for that application is a single file which you must download. The package contains pre-compiled copies of all the commands for the application, as well as any configuration files or documentation. A downloaded package file can be manipulated with DragonFly package management commands, such as [pkg_radd(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_add§ion1), [pkg_delete(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_delete§ion=1), [pkg_info(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_info§ion=1), and so on. Installing a new application can be carried out with a single command.
1917 In addition 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.
1920 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.
1924 **Binary Package Benefits**
1929 * A compressed package tarball is typically smaller than the compressed tarball containing the source code for the application.
1932 * 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.
1935 * Packages do not require any understanding of the process involved in compiling software on DragonFly.
1939 **Pkgsrc source Benefits**
1944 * 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.
1947 * 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.
1950 * The licensing conditions of some software distributions forbid binary distribution. They must be distributed as source code.
1953 * 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.
1956 * If you have local patches, you will need the source in order to apply them.
1959 * Some people like having code around, so they can read it if they get bored, hack it, borrow from it (license permitting, of course), and so on.
1963 To keep track of updated 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.
1967 **Warning:** Before installing any application, you should check http://www.pkgsrc.org/ for security issues related to your application.
1971 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.
1976 ## Finding Your Application
1980 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:
1982 Since DragonFly 1.11 [pkg_search(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_search§ion1) is included in the base system. [pkg_search(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_search§ion=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§ion=5) file.
1984 **Example. Find a Package**
1987 fvwm-2.4.20nb1 Newer version of X11 Virtual window manager
1988 fvwm-2.5.24 Development version of X11 Virtual window manager
1989 fvwm-themes-0.6.2nb8 Configuration framework for fvwm2 with samples
1990 fvwm-wharf-1.0nb1 Copy of AfterStep's Wharf compatible with fvwm2
1991 fvwm1-1.24rnb1 Virtual window manager for X
1995 # pkg_search -v fvwm-2.5
1996 Name : fvwm-2.5.24-50
1998 Desc : Development version of X11 Virtual window manager
2000 Deps : perl>#5.0 gettext-lib>0.14.5 png>=1.2.4 libXext>=0.99.0 libX11>=1.1 libXau>=1.0 libXdmcp>=0.99 libX11>=0.99 libXft>=2.1.10 fontconfig>=2.2 freetype2>=2.1.8
2001 freetype2>=2.1.3 expat>=1.95.7 expat>=1.95.4 freetype2>=2.1.10nb1 expat>=2.0.0nb1 fontconfig>=2.4.2 fontconfig>=2.1nb2 libXrender>=0.9.2 libXpm>=3.5.4.2 libXt>=1.0.0
2002 libSM>=0.99.2 libICE>=0.99.1 png>=1.2.9nb2
2005 To get more verbose information about a package (dependencies, path in `/usr/pkgsrc`, Description) use the `-v` switch.
2007 There is a pkgsrc® related web site that maintains an up-to-date searchable list of all the available applications, at [http://pkgsrc.se](http://pkgsrc.se). The packages and the corresponding source tree are divided into categories, and you may either search for an application by name (if you know it), or see all the applications available in a category.
2009 ## Get the description of a package
2011 To get a more verbose description of the package use pkg_search's `-s` switch with the exact package name (e.g. as given by a normal query):
2013 # pkg_search -s fvwm-2.5.24
2014 Fvwm is a very famous window manager for X, which provides a
2015 virtual/multiple disjoint desktop, a 3-D look for windows decorations,
2016 shaped/color icons. It gives a very good emulation of mwm. A nice
2017 button-bar can be used to provide convenient access to frequently used
2018 functions or programs.
2020 This package is based on the unstable 2.5.x series of fvwm. Do not
2021 use it unless comfortable running beta software.
2024 **Note:** To use the `-s` switch you need a complete pkgsrc tree installed.
2028 ## Using the Binary Packages System
2032 ***DragonFly customizations contributed by Chern Lee and Adrian Nida. ***
2036 ### Installing a Binary Package
2038 You can use the [pkg_add(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_add§ion=1) utility to install a pkgsrc® software package from a local file or from a server on the network.
2040 The [pkg_radd(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_radd§ion=1) tool conveniently fetches and installs the requested package from one of DragonFly's pkg servers without having to know the full URL to it.
2042 <!-- XXX: put in pkg_radd example, it's more meaningful; also check the url below (ftp.pkgsrc-box.org) -->
2045 Binary package files are distributed in `.tgz` formats. You can find them at the default location ftp://ftp.pkgsrc-box.org/packages/, among other sites. The layout of the packages is similar to that of the `/usr/pkgsrc` tree. Each category has its own directory, and every package can be found within the `All` directory.
2049 The directory structure of the binary package system matches the source tree layout; they work with each other to form the entire package system.
2053 Since DragonFly 1.11 you can use [pkg_radd(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_radd§ion=1) to install binary packages without having to set `PACKAGESITE` or providing the complete URL. [pkg_radd(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_radd§ion=1) will handle that for you:
2061 ### Dealing with different package versions
2063 Due to the fact that the official packages are only build for the RELEASE-Version of DragonFly, it is possible that you see a warning when installing binary packages on a DEVELOPMENT-version of DragonFly. The warning could look like this:
2065 pkg_add: Warning: package `vim-gtk2-7.1.116.tgz' was built for a different version of the OS:
2066 pkg_add: DragonFly/i386 1.10.1 (pkg) vs. DragonFly/i386 1.11.0 (this host)
2068 You can safely ignore this warning. Normally all packages build for RELEASE run fine on DEVELOPMENT unless a major API-breakage was introduced. In this case you would see a message from the developers on the appropriate mailing list.
2070 ### Managing Packages
2072 [pkg_info(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_info§ion=1) is a utility that lists and describes the various packages installed.
2077 digest-20050731 Message digest wrapper utility
2078 screen-4.0.2nb4 Multi-screen window manager
2081 [pkg_version(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_version§ion=1) is a utility that summarizes the versions of all installed packages. It compares the package version to the current version found in the ports tree.
2083 ### Deleting a Package
2085 To remove a previously installed software package, use the [pkg_delete(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_delete§ion=1) utility.
2088 # pkg_delete screen-4.0.3.tgz
2092 All package information is stored within the `/var/db/pkg` directory. The installed file list and descriptions of each package can be found within subdirectories of this directory.
2096 ## Using the pkgsrc® Source Tree
2098 The following sections provide basic instructions on using the pkgsrc source tree to install or remove programs from your system.
2100 ### Obtaining the pkgsrc Source Tree
2102 Before you can install pkgsrc® packages from source, you must first obtain the pkgsrc source tree--which is essentially a set of `Makefiles`, patches, and description files placed in `/usr/pkgsrc`.
2106 The primary method to obtain and keep your pkgsrc collection up to date is by using **CVS**. This is a quick method for getting the pkgsrc collection using **CVS** .
2111 # cvs -d anoncvs@anoncvs.us.netbsd.org:/cvsroot co pkgsrc
2114 Running the following command later will download and apply all the recent changes to your source tree.
2120 #### The DragonFly Way
2122 <!-- XXX: mention our git repo of pkgsrc -->
2125 As of the 1.10 release, you can use the `/usr/Makefile` to checkout & update the pkgsrc tree quickly.
2131 # make pkgsrc-create
2133 to checkout from git repository, or
2137 # make pkgsrc-update
2139 to update. **NOTE**: If you use CVS instead of git please do edit the Makefile to use an appropriately speedy CVS mirror for your location and to reduce load on the main pkgsrc CVS server.
2141 ### Installing Packages from Source
2143 The first thing that should be explained when it comes to the source tree is what is actually meant by a ***skeleton***. In a nutshell, a source skeleton is a minimal set of files that tell your DragonFly system how to cleanly compile and install a program. Each source skeleton should include:
2145 * A `Makefile`. The `Makefile` contains various statements that specify how the application should be compiled and where it should be installed on your system.
2148 * A `distinfo` file. This file contains information about the files that must be downloaded to build the port and their checksums, to verify that files have not been corrupted during the download using [md5(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=md5§ion=1).
2151 * A `files` directory. This directory contains the application specific files that are needed for the programs appropriate run-time configuration.
2153 This directory may also contain other files used to build the port.
2156 * A `patches` directory. This directory contains patches to make the program compile and install on your DragonFly system. Patches are basically small files that specify changes to particular files. They are in plain text format, and basically say <i>Remove line 10</i> or <i>Change line 26 to this ...</i>. Patches are also known as <i>diffs</i> because they are generated by the [diff(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#diff§ion1) program.
2159 * A `DESCR` file. This is a more detailed, often multiple-line, description of the program.
2162 * A `PLIST` file. This is a list of all the files that will be installed by the port. It also tells the pkgsrc system what files to remove upon deinstallation.
2166 Some pkgsrc source skeletons have other files, such as `MESSAGE`. The pkgsrc system uses these files to handle special situations. If you want more details on these files, and on pkgsrc in general, check out [The pkgsrc guide](http://www.netbsd.org/Documentation/pkgsrc/), available at the [NetBSD website](http://www.netbsd.org/).
2170 Now that you have enough background information to know what the pkgsrc source tree is used for, you are ready to install your first compiled package. There are two ways this can be done, and each is explained below.
2172 Another way to find a particular source tree is by using the pkgsrc collection's built-in search mechanism. To use the search feature, you will need to be in the `/usr/pkgsrc` directory. Once in that directory, run `bmake search key=program-name` where `program-name` is the name of the program you want to find. This searches packages names, comments, descriptions and dependencies and can be used to find packages which relate to a particular subject if you don't know the name of the program you are looking for. For example, if you were looking for `apache2`:
2176 # bmake search key="apache2"
2177 Extracting complete dependency database. This may take a while...
2178 ....................................................................................................
2180 ....................................................................................................
2184 ....................................................................................................
2186 .................................................................................................Reading database file
2187 Flattening dependencies
2188 Flattening build dependencies
2189 Generating INDEX file
2190 Indexed 5999 packages
2192 Pkg: apache-2.2.6nb2
2194 Info: Apache HTTP (Web) server, version 2
2195 Maint: tron@NetBSD.org
2197 B-deps: perl>#5.0 apr-util>1.2.8 apr>=1.2.8 libtool-base>=1.5.22nb1 pkg-config>=0.19 expat>=1.95.7 gmake>=3.78 gettext-lib>=0.14.5
2198 {gettext-tools>=0.14.5,gettext>=0.10.36<0.14.5} expat>=1.95.4 expat>=2.0.0nb1 apr-util>=1.2.8nb1
2199 R-deps: perl>#5.0 apr-util>1.2.8 apr>=1.2.8 expat>=1.95.7 expat>=1.95.4 expat>=2.0.0nb1 apr-util>=1.2.8nb1
2203 The part of the output you want to pay particular attention to is the <i>Path</i> line, since that tells you where to find the source tree for the requested application. The other information provided is not needed in order to install the package, so it will not be covered here.
2205 The search string is case-insensitive. Searching for <i>APACHE</i> will yield the same results as searching for <i>apache</i>.
2209 **Note:** It should be noted that <i>Extracting [the] complete dependency database</i> does indeed take a while.
2213 **Note:** You must be logged in as `root` to install packages.
2217 Now that you have found an application you would like to install, you are ready to do the actual installation. The source package includes instructions on how to build source code, but does not include the actual source code. You can get the source code from a CD-ROM or from the Internet. Source code is distributed in whatever manner the software author desires. Frequently this is a tarred and gzipped file, but it might be compressed with some other tool or even uncompressed. The program source code, whatever form it comes in, is called a ***distfile***. You can get the distfile from a CD-ROM or from the Internet.
2221 **Warning:** Before installing any application, you should be sure to have an up-to-date source tree and you should check http://www.pkgsrc.org/ for security issues related to your port.
2224 A security vulnerabilities check can be automatically done by **audit-packages** before any new application installation. This tool can be found in the pkgsrc collection ([security/audit-packages](http://pkgsrc.se/security/audit-packages)). Consider running `auditpackages -d` before installing a new package, to fetch the current vulnerabilities database. A security audit and an update of the database will be performed during the daily security system check. For more informations read the audit-packages and [periodic(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#periodic§ion8) manual pages.
2228 **Note:** It should be noted that the current setup of DragonFly requires the use of `bmake` instead of `make`. This is because the current version of make on DragonFly does not support all the parameters that NetBSD's does.
2232 **Note:** You can save an extra step by just running `bmake install` instead of `bmake` and `bmake install` as two separate steps.
2236 **Note:** Some shells keep a cache of the commands that are available in the directories listed in the `PATH` environment variable, to speed up lookup operations for the executable file of these commands. If you are using one of these shells, you might have to use the `rehash` command after installing a package, before the newly installed commands can be used. This is true for both shells that are part of the base-system (such as `tcsh`) and shells that are available as packages (for instance, [shells/zsh](http://pkgsrc.se/shells/zsh)).
2238 <!-- XXX: mention the stuff about the pkgsrc security audit thingie -->
2240 #### Installing Packages from the Internet
2244 As with the last section, this section makes an assumption that you have a working Internet connection. If you do not, you will need to put a copy of the distfile into `/usr/pkgsrc/distfiles` manually. Installing a package from the Internet is done exactly the same way as it would be if you already had the distfile. The only difference between the two is that the distfile is downloaded from the Internet on demand.
2247 Here are the steps involved:
2250 # cd /usr/pkgsrc/chat/ircII
2251 # bmake install clean
2252 => ircii-20040820.tar.bz2 doesn't seem to exist on this system.
2253 => Attempting to fetch ircii-20040820.tar.bz2 from ftp://ircii.warped.com/pub/ircII/.
2255 [FTP transfer snipped]
2256 150 Opening BINARY mode data connection for 'ircii-20040820.tar.bz2' (559843 bytes).
2257 100% |***************************************| 550 KB 110.34 KB/s 00:00 ETA
2258 226 Transfer complete.
2259 [FTP transfer snipped]
2260 221 Thank you for using the FTP service on bungi.sjc.warped.net.
2261 => Checksum SHA1 OK for ircii-20040820.tar.bz2.
2262 => Checksum RMD160 OK for ircii-20040820.tar.bz2.
2263 work -> /usr/obj/pkgsrc/chat/ircII/work
2264 ##=> Extracting for ircII-20040820
2265 #########################################################################=
2266 The supported build options for this package are:
2270 You can select which build options to use by setting PKG_DEFAULT_OPTIONS
2271 or the following variable. Its current value is shown:
2274 PKG_OPTIONS.ircII (not defined)
2276 #########################################################################=
2277 #########################################################################=
2278 The following variables will affect the build process of this package,
2279 ircII-20040820. Their current value is shown below:
2283 You may want to abort the process now with CTRL-C and change their value
2284 before continuing. Be sure to run `/usr/pkg/bin/bmake clean' after
2286 #########################################################################=
2287 ##=> Patching for ircII-20040820
2288 ##=> Applying pkgsrc patches for ircII-20040820
2289 ##=> Overriding tools for ircII-20040820
2290 ##=> Creating toolchain wrappers for ircII-20040820
2291 ##=> Configuring for ircII-20040820
2293 [configure output snipped]
2295 ##=> Building for ircII-20040820
2297 [compilation output snipped]
2299 ##=> Installing for ircII-20040820
2301 [installation output snipped]
2303 ##=> [Automatic manual page handling]
2304 ##=> Registering installation for ircII-20040820
2305 ##=> Cleaning for ircII-20040820
2310 <!-- XXX: mention /usr/pkg/etc/mk.conf for options, etc -->
2312 As you can see, the only difference are the lines that tell you where the system is fetching the package's distfile from.
2316 The pkgsrc system uses [ftp(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ftp§ion=1) to download the files, which honors various environment variables, including `FTP_PASSIVE_MODE`, `FTP_PROXY`, and `FTP_PASSWORD`. You may need to set one or more of these if you are behind a firewall, or need to use an FTP/HTTP proxy. See [ftp(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ftp§ion=1) for the complete list.
2320 For users which cannot be connected all the time, the `bmake fetch` option is provided. Just run this command at the top level directory (`/usr/pkgsrc`) and the required files will be downloaded for you. This command will also work in the lower level categories, for example: `/usr/pkgsrc/net`. Note that if a package depends on libraries or other packages this will ***not*** fetch the distfiles of those packages as well.
2324 **Note:** You can build all the packages in a category or as a whole by running `bmake` in the top level directory, just like the aforementioned `bmake `fetch*** method. This is dangerous, however, as some applications cannot co-exist. In other cases, some packages can install two different files with the same filename.
2328 In some rare cases, users may need to acquire the tarballs from a site other than the `MASTER_SITES` (the location where files are downloaded from). You can override the `MASTER_SORT`, `MASTER_SORT_REGEX` and `INET_COUNTRY` options either within the `/etc/mk.conf`.
2332 **Note:** Some packages allow (or even require) you to provide build options which can enable/disable parts of the application which are unneeded, certain security options, and other customizations. A few which come to mind are [`www/mozilla`](http://pkgsrc.se/www/mozilla), [`security/gpgme`](http://pkgsrc.se/security/gpgme), and [`mail/sylpheed-claws`](http://pkgsrc.se/mail/sylpheed-claws). To find out what build options the application you are installing requires type:
2338 # bmake show-options
2344 To change the build process, either change the values of PKG_DEFAULT_OPTIONS or PKG_OPTIONS.`***PackageName***` in `/etc/mk.conf` or on the commandline as so:
2350 # bmake PKG_OPTIONS.ircII="-ssl"
2356 An option is enabled if listed. It is disabled if it is prefixed by a minus sign.
2360 #### Dealing with imake
2364 Some applications that use `imake` (a part of the X Window System) do not work well with `PREFIX`, and will insist on installing under `/usr/X11R6`. Similarly, some Perl ports ignore `PREFIX` and install in the Perl tree. Making these applications respect `PREFIX` is a difficult or impossible job.
2368 ### Removing Installed Packages
2372 Now that you know how to install packages, you are probably wondering how to remove them, just in case you install one and later on decide that you installed the wrong program. We will remove our previous example (which was `ircII` for those of you not paying attention). As with installing packages, the first thing you must do is change to the package directory, `/usr/pkgsrc/chat/ircII`. After you change directories, you are ready to uninstall `ircII`. This is done with the `bmake deinstall` command:
2376 # cd /usr/pkgsrc/chat/ircII
2378 ##=> Deinstalling for ircII-20040820
2381 That was easy enough. You have removed `ircII` from your system. If you would like to reinstall it, you can do so by running `bmake reinstall` from the `/usr/pkgsrc/chat/ircII` directory.
2385 The `bmake deinstall` and `bmake reinstall` sequence does not work once you have run `bmake clean`. If you want to deinstall a package after cleaning, use [pkg_delete(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_delete§ion=1) as discussed in the [pkgsrc-using.html Pkgsrc section of the Handbook].
2389 ### Packages and Disk Space
2393 Using the pkgsrc collection can definitely eat up your disk space. For this reason you should always remember to clean up the work directories using `bmake clean`. This will remove the `work` directory after a package has been built, and installed. You can also remove the tar files from the `distfiles` directory, and remove the installed package when their use has delimited.
2397 ### Upgrading Packages
2400 **Note:** Once you have updated your pkgsrc collection, before attempting a package upgrade, you should check the `/usr/pkgsrc/UPDATING` file. This file describes various issues and additional steps users may encounter and need to perform when updating a port.
2404 Keeping your packages up to date can be a tedious job. For instance, to upgrade a package you would go to the package directory, build the package, deinstall the old package , install the new package, and then clean up after the build. Imagine doing that for five packages, tedious right? This was a large problem for system administrators to deal with, and now we have utilities which do this for us. For instance the `pkg_chk` utility will do everything for you!
2408 pkg_chk requires a few steps in order to work correctly. They are listed here.
2410 # pkg_chk -g # make initial list of installed packages
2411 # pkg_chk -r # remove all packages that are not up to date and packages that depend on them
2412 # pkg_chk -a # install all missing packages (use binary packages, this is the default
2413 # pkg_chk -as # install all missing packages (build from source)
2415 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. "pkg_rolling-replace" replaces packages one by one and one can use it for a better way of package management. You can install "pkg_rolling-replace" by the following procedure.
2417 # cd /usr/pkgsrc/pkgtools/pkg_rolling-replace/
2420 Once pkg_rolling-replace is installed you can update the packages through the following steps.
2422 # cd /usr && make pkgsrc-update
2423 # pkg_rolling-replace -u
2425 If some package like "bmake" does not get updated and throws an error during the above steps you can update it manually.
2426 Inside the packages directory (devel/bmake in this case)
2428 # env USE_DESTDIR=full bmake package
2429 # bmake clean-depends clean
2431 And Go to the packages directory and install the binary package with
2433 # pkg_add -u <pkg_name> (i.e. the name of the .tgz file).
2435 Also you can use "pkgin" to update software using binary packages just like apt or yum.
2437 # cd /usr/pkgsrc/pkgtools/pkgin/
2440 Once "pkgin" is installed edit "/usr/pkg/etc/pkgin/repositories.conf" to contain the line ( for i386 packages ).
2442 http://avalon.dragonflybsd.org/packages/i386/DragonFly-2.5/stable/All
2444 Then you can run the following commands to get the packages updated.
2447 # pkgin full-upgrade
2451 ## Post-installation Activities
2455 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.
2459 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:
2464 Use [pkg_info(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_info§ion=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
2466 # pkg_info -L foopackage-1.0.0 | less
2468 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
2472 pkg_info | grep -i foopackage
2475 will find all the installed packages that have <i>foopackage</i> in the package name. Replace <i>foopackage</i> in your command line as necessary.
2478 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§ion=1). Similarly, look over the sample configuration files, and any additional documentation that may have been provided.
2481 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
2485 # pkg_info foopackage-1.0.0
2488 A `WWW:` line, if present, should provide a URL for the application's web site.
2491 Packages that should start at boot (such as Internet servers) will usually install a sample script in `/usr/pkg/etc/rc.d`. You should review this script for correctness and edit or rename it if needed.
2498 ## Dealing with Broken Packages
2502 If you come across a package that does not work for you, there are a few things you can do, including:
2506 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!
2508 1. Gripe--***by email only***! 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/) .
2510 1. Grab the package from an FTP site near you. The ***master*** package collection is on `packages.stura.uni-rostock.de` in the [All directory](ftp://packages.stura.uni-rostock.de/pkgsrc-current/DragonFly/RELEASE/i386/All/). These are more likely to work than trying to compile from source and are a lot faster as well. Use the [pkg_add(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_add§ion=1) program to install the package on your system.
2520 CategoryHandbook-pkgsrc
2540 # The X Window System
2544 ***Updated for X.Org's X11 server by Ken Tom and Marc Fonvieille. Updated for DragonFly by Victor Balada Diaz.***
2549 DragonFly uses X11 to provide users with a powerful graphical user interface. X11 is an open-source implementation of the X Window System that includes both **X.org** and **XFree86™** . DragonFly default official flavor is **X.org** , the X11 server developed by the X.Org Foundation. This chapter will cover the installation and configuration of X11 with emphasis on **X.org** . For more information on the video hardware that X11 supports, check either the [X.org](http://www.x.org/) or [XFree86](http://www.XFree86.org/) web sites.
2553 After reading this chapter, you will know:
2558 * The various components of the X Window System, and how they interoperate.
2559 * How to install and configure X11.
2560 * How to install and use different window managers.
2561 * How to use True***Type® fonts in X11.
2562 * How to set up your system for graphical logins ( **XDM** ).
2566 Before reading this chapter, you should:
2568 * Know how to install additional third-party software. Compare the pkgsrc chapter of the handbook.
2570 **Note:** This chapter covers the installation and the configuration of both **X.org** and **XFree86** X11 servers. For the most part, configuration files, commands and syntaxes are identical. In the case where there are differences, both **X.org** and **XFree86** syntaxes will be shown.
2579 ## The Window Manager
2583 The X design philosophy is much like the UNIX design philosophy, ***tools, not policy***. This means that X does not try to dictate how a task is to be accomplished. Instead, tools are provided to the user, and it is the user's responsibility to decide how to use those tools. This philosophy extends to X not dictating what windows should look like on screen, how to move them around with the mouse, what keystrokes should be used to move between windows (i.e., **Alt** + **Tab** , in the case of Microsoft Windows), what the title bars on each window should look like, whether or not they have close buttons on them, and so on.
2587 Instead, X delegates this responsibility to an application called a ***Window Manager***. There are dozens of window managers available for X: ***'After***Step***', **Blackbox** , **ctwm** , **Enlightenment** , **fvwm** , **Sawfish** , **twm** , **Window Maker** , and more. Each of these window managers provides a different look and feel; some of them support ***virtual desktops***; some of them allow customized keystrokes to manage the desktop; some have a ***Start*** button or similar device; some are ***themeable***, allowing a complete change of look-and-feel by applying a new theme. These window managers, and many more, are available in the `x11-wm` category of the Ports Collection.
2591 In addition, the **KDE** and **GNOME** desktop environments both have their own window managers which integrate with the desktop. Each window manager also has a different configuration mechanism; some expect configuration file written by hand, others feature GUI tools for most of the configuration tasks; at least one ( **Sawfish** ) has a configuration file written in a dialect of the Lisp language.
2599 **X.org** or **XFree86™** may be installed on DragonFly. DragonFly doesn't force a default implementation, but recommends **X.org** . **X.org** is the X server of the open source X Window System implementation released by the X.Org Foundation and is based on the code of **XFree86 4.4RC2** and !X11R6.6. **X.org** is currently available in the DragonFly pkgsrc framework.
2601 To build and install **X.org** from the pkgsrc framework:
2602 # echo "X11_TYPE=modular" >> /etc/mk.conf
2605 Now 5 different packages need to be built and installed:
2607 # cd /usr/pkgsrc/x11/modular-xorg-server
2608 # bmake install clean
2609 # cd /usr/pkgsrc/meta-pkgs/modular-xorg-drivers
2610 # bmake install clean
2611 # cd /usr/pkgsrc/meta-pkgs/modular-xorg-fonts
2612 # bmake install clean
2613 # cd /usr/pkgsrc/meta-pkgs/modular-xorg-libs
2614 # bmake install clean
2615 # cd /usr/pkgsrc/meta-pkgs/modular-xorg-apps
2616 # bmake install clean
2620 Alternatively, X11 can be installed directly from packages. Binary packages to use with [pkg_radd(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_radd§ion=1) tool are also available for X11.So to fetch and install the package of **X.org**, type:
2623 # pkg_radd modular-xorg-server
2624 # pkg_radd modular-xorg-drivers
2625 # pkg_radd modular-xorg-libs
2626 # pkg_radd modular-xorg-apps
2627 # pkg_radd modular-xorg-fonts
2630 **Note:** The examples above will install the complete X11 distribution including the server, drivers, fonts etc. Separate packages and ports of X11 are also available.
2639 ## 5.4 X11 Configuration
2643 ***Contributed by Christopher Shumway. ***
2647 ### 5.4.1 Before Starting
2651 Before configuration of X11 the following information about the target system is needed:
2656 * Monitor specifications
2659 * Video Adapter chipset
2662 * Video Adapter memory
2666 The specifications for the monitor are used by X11 to determine the resolution and refresh rate to run at. These specifications can usually be obtained from the documentation that came with the monitor or from the manufacturer's website. There are two ranges of numbers that are needed, the horizontal scan rate and the vertical synchronization rate.
2670 The video adapter's chipset defines what driver module X11 uses to talk to the graphics hardware. With most chipsets, this can be automatically determined, but it is still useful to know in case the automatic detection does not work correctly.
2674 Video memory on the graphic adapter determines the resolution and color depth which the system can run at. This is important to know so the user knows the limitations of the system.
2678 ### 5.4.2 Configuring X11
2682 As of version 7.3, Xorg can often work without any configuration file by simply typing at prompt:
2691 If this does not work, or if the default configuration is not acceptable, then X11 must be configured manually. Configuration of X11 is a multi-step process. The first step is to build an initial configuration file. As the super user, simply run:
2698 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&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.
2702 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:
2706 # Xorg -config xorg.conf.new
2709 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.
2713 **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`:
2719 Next, tune the `xorg.conf.new` configuration file to taste. Open the file in a text editor such as [vi(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=vi§ion=1) or [ee(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ee&section=1). First, add the frequencies for the target system's monitor. These are usually expressed as a horizontal and vertical synchronization rate. These values are added to the `xorg.conf.new` file under the `"Monitor"` section:
2724 Identifier "Monitor0"
2725 VendorName "Monitor Vendor"
2726 ModelName "Monitor Model"
2733 The `HorizSync` and `VertRefresh` keywords may be missing in the configuration file. If they are, they need to be added, with the correct horizontal synchronization rate placed after the `HorizSync` keyword and the vertical synchronization rate after the `VertRefresh` keyword. In the example above the target monitor's rates were entered.
2737 X allows DPMS (Energy Star) features to be used with capable monitors. The [xset(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=xset§ion=1) program controls the time-outs and can force standby, suspend, or off modes. If you wish to enable DPMS features for your monitor, you must add the following line to the monitor section:
2743 While the `xorg.conf.new` configuration file is still open in an editor, select the default resolution and color depth desired. This is defined in the `"Screen"` section:
2750 Identifier "Screen0"
2754 SubSection "Display"
2762 The `DefaultDepth` keyword describes the color depth to run at by default. This can be overridden with the `-depth` command line switch to [Xorg(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=xorg§ion=1). The `Modes` keyword describes the resolution to run at for the given color depth. Note that only VESA standard modes are supported as defined by the target system's graphics hardware. In the example above, the default color depth is twenty-four bits per pixel. At this color depth, the accepted resolution is 1024 by 768 pixels.
2765 Finally, write the configuration file and test it using the test mode given above.
2768 **Note:** One of the tools available to assist you during troubleshooting process are the X11 log files, which contain information on each device that the X11 server attaches to. **X.org** log file names are in the format of `/var/log/Xorg.0.log`. The exact name of the log can vary from `Xorg.0.log` to `Xorg.8.log` and so forth.
2772 If all is well, the configuration file needs to be installed in a common location where [Xorg(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=xorg§ion=1) can find it. This is typically `/etc/X11/xorg.conf` or `/usr/pkg/xorg/lib/X11/xorg.conf`.
2776 # cp xorg.conf.new /etc/X11/xorg.conf
2780 The X11 configuration process is now complete. You can start **X.org** with [startx(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=startx§ion=1). The X11 server may also be started with the use of [xdm(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=xdm§ion=1).
2783 **Note:** There is also a graphical configuration tool, [xorgcfg(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=xorgcfg§ion=1), that comes with the X11 distribution. It allows you to interactively define your configuration by choosing the appropriate drivers and settings. This program can be invoked from the console, by typing the command `xorgcfg -textmode`. For more details, refer to the [xorgcfg(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=xorgcfg§ion=1) manual page.
2786 Alternatively, there is also a tool called [xorgconfig(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=xorgconfig§ion=1), this program is a console utility that is less user friendly, but it may work in situations where the other tools do not.
2790 ### 5.4.3 Advanced Configuration Topics
2794 #### 5.4.3.1 Configuration with Intel® i810 Graphics Chipsets
2798 Configuration with Intel® i810 integrated chipsets requires the `agpgart` AGP programming interface for X11 to drive the card. See the [agp(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=agp&section=4) driver manual page for more information.
2801 This will allow configuration of the hardware as any other graphics board. Note on systems without the [agp(4)](http://leaf.dragonflybsd.org/cgi/web-man?command#agp§ion4) driver compiled in the kernel, trying to load the module with [kldload(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=kldload§ion=8) will not work. This driver has to be in the kernel at boot time through being compiled in or using `/boot/loader.conf`.
2804 **Note:** If you are using **XFree86 4.1.0** (or later) and messages about unresolved symbols like `fbPictureInit` appear, try adding the following line after `Driver "i810"` in the X11 configuration file:
2819 # 5.5 Using Fonts in X11
2820 <!-- XXX: do we really need this? -->
2823 ***Contributed by Murray Stokely. ***
2827 ## 5.5.1 Type1 Fonts
2831 The default fonts that ship with X11 are less than ideal for typical desktop publishing applications. Large presentation fonts show up jagged and unprofessional looking, and small fonts in **Netscape®** are almost completely unintelligible. However, there are several free, high quality Type1 (Post***Script®) fonts available which can be readily used with X11. For instance, the Freefonts collection (['fonts/freefonts'](http://pkgsrc.se/fonts/freefonts)) includes a lot of fonts, but most of them are intended for use in graphics software such as the **Gimp** , and are not complete enough to serve as screen fonts. In addition, X11 can be configured to use True***Type® fonts with a minimum of effort. For more details on this, see the [X(7)](http://leaf.dragonflybsd.org/cgi/web-man?command=X§ion=7) manual page or the [ section on TrueType fonts](x-fonts.html#TRUETYPE).
2835 To install the Freefonts font collection from the pkgsrc framework, run the following commands:
2841 # cd /usr/pkgsrc/fonts/freefonts
2843 # bmake install clean
2849 And likewise with the other collections. To have the X server detect these fonts, add an appropriate line to the X server configuration file in `/etc/X11/xorg.conf`, which reads:
2855 FontPath "/usr/pkg/lib/X11/fonts/freefont/"
2861 Alternatively, at the command line in the X session run:
2867 % xset fp+ /usr/pkg/lib/X11/fonts/freefont/
2875 This will work but will be lost when the X session is closed, unless it is added to the startup file (`~/.xinitrc` for a normal `startx` session, or `~/.xsession` when logging in through a graphical login manager like **XDM** ). A third way is to use the new `/usr/pkg/xorg/etc/fonts/local.conf` file: see the section on [ anti-aliasing](x-fonts.html#ANTIALIAS).
2879 ## 5.5.2 TrueType® Fonts
2883 **X.org** has built in support for rendering True***Type fonts. There are two different modules that can enable this functionality. The freetype module is used in this example because it is more consistent with the other font rendering back-ends. To enable the freetype module just add the following line to the `"Module"` section of the `/etc/X11/xorg.conf` file.
2895 Now make a directory for the True***Type fonts (for example, `/usr/pkg/xorg/lib/X11/fonts/TrueType`) and copy all of the True***Type fonts into this directory. Keep in mind that True***Type fonts cannot be directly taken from a Macintosh®; they must be in UNIX®/MS-DOS®/Windows® format for use by X11. Once the files have been copied into this directory, use **ttmkfdir** to create a `fonts.dir` file, so that the X font renderer knows that these new files have been installed. 'ttmkfdir' is available from the pkgsrc framework as [`fonts/ttmkfdir2`](http://pkgsrc.se/fonts/ttmkfdir2).
2901 # cd /usr/pkg/xorg/lib/X11/fonts/TrueType
2903 # ttmkfdir -o fonts.dir
2909 Now add the True***Type directory to the font path. This is just the same as described above for [ Type1](x-fonts.html#TYPE1) fonts, that is, use
2915 % xset fp+ /usr/pkg/xorg/lib/X11/fonts/TrueType
2923 or add a `FontPath` line to the `xorg.conf` file.
2927 That's it. Now **Netscape** , **Gimp** , ***'Star***Office™***', and all of the other X applications should now recognize the installed True***Type fonts. Extremely small fonts (as with text in a high resolution display on a web page) and extremely large fonts (within **Star`Office** ) will look much better now.
2931 ## 5.5.3 Anti-Aliased Fonts
2935 ***Updated by Joe Marcus Clarke. ***
2939 Anti-aliasing has been available in X11 since **XFree86** 4.0.2. However, font configuration was cumbersome before the introduction of **XFree86** 4.3.0. Beginning with **XFree86** 4.3.0, all fonts in X11 that are found in `/usr/pkg/xorg/lib/X11/fonts/` and `~/.fonts/` are automatically made available for anti-aliasing to Xft-aware applications. Not all applications are Xft-aware, but many have received Xft support. Examples of Xft-aware applications include Qt 2.3 and higher (the toolkit for the **KDE** desktop), GTK+ 2.0 and higher (the toolkit for the **GNOME** desktop), and **Mozilla** 1.2 and higher.
2943 In order to control which fonts are anti-aliased, or to configure anti-aliasing properties, create (or edit, if it already exists) the file `/usr/pkg/xorg/lib/etc/fonts/local.conf`. Several advanced features of the Xft font system can be tuned using this file; this section describes only some simple possibilities. For more details, please see [fonts-conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=fonts-conf§ion=5).
2947 This file must be in XML format. Pay careful attention to case, and make sure all tags are properly closed. The file begins with the usual XML header followed by a DOCTYPE definition, and then the `<fontconfig>` tag:
2953 <?xml version="1.0"?>;
2955 <!DOCTYPE fontconfig SYSTEM "fonts.dtd">
2963 As previously stated, all fonts in `/usr/pkg/xorg/lib/X11/fonts/` as well as `~/.fonts/` are already made available to Xft-aware applications. If you wish to add another directory outside of these two directory trees, add a line similar to the following to `/usr/pkg/lib/etc/fonts/local.conf`:
2969 <dir>/path/to/my/fonts</dir>;
2975 After adding new fonts, and especially new font directories, you should run the following command to rebuild the font caches:
2987 Anti-aliasing makes borders slightly fuzzy, which makes very small text more readable and removes "staircases" from large text, but can cause eyestrain if applied to normal text. To exclude font sizes smaller than 14 point from anti-aliasing, include these lines:
2993 <match target="font">
2995 <test name#"size" compare"less">
3001 <edit name#"antialias" mode"assign">
3009 <match target="font">
3011 <test name#"pixelsize" compare"less" qual="any">
3017 <edit mode#"assign" name"antialias">
3029 Spacing for some monospaced fonts may also be inappropriate with anti-aliasing. This seems to be an issue with **KDE** , in particular. One possible fix for this is to force the spacing for such fonts to be 100. Add the following lines:
3035 <match target#"pattern" name"family">
3037 <test qual#"any" name"family">
3039 <string>fixed</string>
3043 <edit name#"family" mode"assign">
3045 <string>mono</string>
3051 <match target#"pattern" name"family">
3053 <test qual#"any" name"family">
3055 <string>console</string>
3059 <edit name#"family" mode"assign">
3061 <string>mono</string>
3071 (this aliases the other common names for fixed fonts as `"mono"`), and then add:
3077 <match target#"pattern" name"family">
3079 <test qual#"any" name"family">
3081 <string>mono</string>
3085 <edit name#"spacing" mode"assign">
3097 Certain fonts, such as Helvetica, may have a problem when anti-aliased. Usually this manifests itself as a font that seems cut in half vertically. At worst, it may cause applications such as **Mozilla** to crash. To avoid this, consider adding the following to `local.conf`:
3103 <match target#"pattern" name"family">
3105 <test qual#"any" name"family">
3107 <string>Helvetica</string>
3111 <edit name#"family" mode"assign">
3113 <string>sans-serif</string>
3123 Once you have finished editing `local.conf` make sure you end the file with the `</fontconfig>` tag. Not doing this will cause your changes to be ignored.
3127 The default font set that comes with X11 is not very desirable when it comes to anti-aliasing. A much better set of default fonts can be found in the ['fonts/vera-ttf'](http://pkgsrc.se/fonts/vera-ttf) port. This port will install a `/usr/pkg/lib/etc/fonts/local.conf` file if one does not exist already. If the file does exist, the port will create a `/usr/pkg/lib/etc/fonts/local.conf-vera ` file. Merge the contents of this file into `/usr/pkg/lib/etc/fonts/local.conf`, and the Bitstream fonts will automatically replace the default X11 Serif, Sans Serif, and Monospaced fonts.
3131 Finally, users can add their own settings via their personal `.fonts.conf` files. To do this, each user should simply create a `~/.fonts.conf`. This file must also be in XML format.
3135 One last point: with an LCD screen, sub-pixel sampling may be desired. This basically treats the (horizontally separated) red, green and blue components separately to improve the horizontal resolution; the results can be dramatic. To enable this, add the line somewhere in the `local.conf` file:
3141 <match target="font">
3143 <test qual#"all" name"rgba">
3145 <const>unknown</const>
3149 <edit name#"rgba" mode"assign">
3161 **Note:** Depending on the sort of display, `rgb` may need to be changed to `bgr`, `vrgb` or `vbgr`: experiment and see which works best.
3167 Anti-aliasing should be enabled the next time the X server is started. However, programs must know how to take advantage of it. At present, the Qt toolkit does, so the entire **KDE** environment can use anti-aliased fonts. GTK+ and **GNOME** can also be made to use anti-aliasing via the "Font" capplet (see [x11-wm.html#X11-WM-GNOME-ANTIALIAS Section 5.7.1.3] for details). By default, **Mozilla** 1.2 and greater will automatically use anti-aliasing. To disable this, rebuild **Mozilla** with the `-DWITHOUT_XFT` flag.
3174 # 5.6 The X Display Manager
3176 ***Contributed by Seth Kingsley.***
3184 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.
3188 Think of **XDM** as providing the same functionality to the user as the [getty(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=getty§ion=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.
3196 The **XDM** daemon program is located in `/usr/pkg/xorg/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:
3202 ttyv8 "/usr/pkg/xorg/bin/xdm -nodaemon" xterm off secure
3208 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§ion=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.
3212 ## 5.6.3 Configuring XDM
3216 The **XDM** configuration directory is located in `/var/lib/xdm`. The sample configuration files are in `/usr/pkg/share/examples/xorg/xdm/`, in this directory there are several files used to change the behavior and appearance of **XDM** . Typically these files will be found:
3220 <tablestyle="width:100%"> **File** | **Description**
3221 <tablestyle="width:100%"> `Xaccess` | Client authorization ruleset.
3222 `Xresources` | Default X resource values.
3223 `Xservers` | List of remote and local displays to manage.
3224 `Xsession` | Default session script for logins.
3225 `Xsetup_`* | Script to launch applications before the login interface.
3226 `xdm-config` | Global configuration for all displays running on this machine.
3227 `xdm-errors` | Errors generated by the server program.
3228 `xdm-pid` | The process ID of the currently running XDM. |
3233 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§ion=1).
3237 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.
3245 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.
3249 ### 5.6.3.2 Xresources
3253 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.
3257 ### 5.6.3.3 Xservers
3261 This is a list of the remote displays the chooser should provide as choices.
3265 ### 5.6.3.4 Xsession
3269 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.
3273 ### 5.6.3.5 Xsetup_*
3277 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`.
3281 ### 5.6.3.6 xdm-config
3285 This contains settings in the form of app-defaults that are applicable to every display that this installation manages.
3289 ### 5.6.3.7 xdm-errors
3293 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.
3297 ## 5.6.4 Running a Network Display Server
3301 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:
3307 ! SECURITY: do not listen for XDMCP or Chooser requests
3309 ! Comment out this line if you want to manage X terminals with xdm
3311 DisplayManager.requestPort: 0
3317 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§ion=1) manual page for further information.
3321 ## 5.6.5 Replacements for XDM
3325 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.
3332 # 5.7 Desktop Environments
3334 ***Contributed by Valentino Vaschetto. ***
3336 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** .
3344 ### 5.7.1.1 About GNOME
3348 **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.
3352 ### 5.7.1.2 Installing GNOME
3356 **GNOME** can be easily installed from a package or from the pkgsrc framework:
3360 To install the **GNOME** package from the network, simply type:
3368 To build **GNOME** from source, use the ports tree:
3372 # cd /usr/pkgsrc/meta-pkgs/gnome
3374 # bmake install clean
3378 Once **GNOME** is installed, the X server must be told to start **GNOME** instead of a default window manager.
3382 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.
3386 **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:
3392 % echo "/usr/pkg/bin/gnome-session" > ~/.xinitrc
3398 Next, type `startx`, and the **GNOME** desktop environment will be started.
3401 **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** :
3407 % echo "#!/bin/sh" > ~/.xsession
3409 % echo "/usr/pkg/bin/gnome-session" >> ~/.xsession
3411 % chmod +x ~/.xsession
3417 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** .
3421 ### 5.7.1.3 Anti-aliased Fonts with GNOME
3425 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).
3427 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.
3435 ### 5.7.2.1 About KDE
3439 **KDE** is an easy to use contemporary desktop environment. Some of the things that **KDE** brings to the user are:
3441 * A beautiful contemporary desktop
3443 * A desktop exhibiting complete network transparency
3445 * An integrated help system allowing for convenient, consistent access to help on the use of the **KDE** desktop and its applications
3447 * Consistent look and feel of all **KDE** applications
3449 * Standardized menu and toolbars, keybindings, color-schemes, etc.
3451 * Internationalization: **KDE** is available in more than 40 languages
3453 * Centralized consisted dialog driven desktop configuration
3455 * A great number of useful **KDE** applications
3457 **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/).
3461 ### 5.7.2.2 Installing KDE
3464 Just as with **GNOME** or any other desktop environment, the easiest way to install **KDE** is through the pkgsrc framework or from a package:
3468 To install the **KDE** package from the network, simply type:
3472 or if you prefer the newer **KDE 4**, type:
3476 [pkg_radd(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#pkg_radd§ion1) will automatically fetch the latest version of the application.
3479 To build **KDE** from source, use the pkgsrc framework:
3481 # cd /usr/pkgsrc/meta-pkgs/kde3
3483 # bmake install clean
3489 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:
3492 % echo "exec startkde" > ~/.xinitrc
3495 Now, whenever the X Window System is invoked with `startx`, **KDE** will be the desktop.
3497 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.
3501 ## 5.7.3 More Details on KDE
3505 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.
3507 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.
3511 ### 5.7.3.1 The KDE Display Manager
3515 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.
3519 To enable **kdm** , the `ttyv8` entry in `/etc/ttys` has to be adapted. The line should look as follows:
3522 ttyv8 "/usr/pkg/bin/kdm -nodaemon" xterm on secure
3530 ### 5.7.4.1 About XFce
3533 **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:
3535 * A simple, easy-to-handle desktop
3537 * Fully configurable via mouse, with drag and drop, etc
3539 * Main panel similar to **CDE** , with menus, applets and applications launchers
3541 * Integrated window manager, file manager, sound manager, **GNOME** compliance module, and other things
3543 * Themeable (since it uses GTK+)
3545 * Fast, light and efficient: ideal for older/slower machines or machines with memory limitations
3548 More information on **XFce** can be found on the [XFce website](http://www.xfce.org/).
3552 ### 5.7.4.2 Installing XFce
3556 A binary package for **XFce** exists. To install, simply type:
3561 Alternatively, to build from source, use the pkgsrc framework:
3565 # cd /usr/pkgsrc/meta-pkgs/xfce4
3567 # bmake install clean
3572 Now, tell the X server to launch **XFce** the next time X is started. Simply type this:
3574 % echo "/usr/pkg/bin/startxfce4" > ~/.xinitrc
3578 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).
3582 <!-- XXX: FreeBSD's handbook has a nice user-oriented section about X applications here. maybe we should have one, too -->
3591 <!-- XXX: break the stuff up here -->
3594 # II. System Administration
3598 The remaining chapters of the DragonFly Handbook cover all aspects of DragonFly system administration. Each chapter starts by describing what you will learn as a result of reading the chapter, and also details what you are expected to know before tackling the material. These chapters are designed to be read when you need the information. You do not have to read them in any particular order, nor do you need to read all of them before you can begin using DragonFly.
3601 ## Chapter 6 Configuration and Tuning
3604 ***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§ion7) written by Matt Dillon.***
3612 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.
3615 After reading this chapter, you will know:
3617 * How to efficiently work with file systems and swap partitions.
3619 * The basics of `rc.conf` configuration and `rc.d` startup systems.
3621 * How to configure and test a network card.
3623 * How to configure virtual hosts on your network devices.
3625 * How to use the various configuration files in `/etc`.
3627 * How to tune DragonFly using `sysctl` variables.
3629 * How to tune disk performance and modify kernel limitations.
3632 Before reading this chapter, you should:
3634 * Understand UNIX® and DragonFly basics ([Chapter 3](basics.html)).
3636 * Be familiar with the basics of kernel configuration/compilation ([Chapter 9](kernelconfig.html)).
3654 ## 6.2 Initial Configuration
3657 ### 6.2.1 Partition Layout
3660 #### 6.2.1.1 Base Partitions
3662 When laying out file systems with [disklabel(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel§ion=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`.
3663 <!-- 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? -->
3667 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.
3671 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.
3675 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.
3679 #### 6.2.1.2 Swap Partition
3683 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.
3684 <!-- XXX: do we really recommend double the RAM for swap? IMHO the amount of RAM should be more than enough -->
3687 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.
3691 #### 6.2.1.3 Why Partition?
3695 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`.
3697 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.
3698 <!-- XXX: again, same story about the edges of disks... -->
3704 CategoryHandbook-configuration
3710 ## 6.3 Core Configuration
3714 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.
3718 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.
3722 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.
3726 As `rc.conf` is read by [sh(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=sh§ion=1) it is trivial to achieve this. For example:
3730 hostname="node15.example.com"
3732 network_interfaces="fxp0 lo0"
3734 ifconfig_fxp0="inet 10.1.1.1"
3741 defaultrouter="10.1.1.254"
3751 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.
3755 Upgrading the system using `make world` will not overwrite the `rc.conf` file, so system configuration information will not be lost.
3760 CategoryHandbook-configuration
3765 ## Application Configuration
3769 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.
3773 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.
3777 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.
3781 For example, consider the contents of the directory `/usr/pkg/etc/httpd`:
3789 -rw-r--r-- 1 root wheel - 34K Jan 11 12:04 httpd.conf
3791 -rw-r--r-- 1 root wheel - 13K Jan 11 12:02 magic
3793 -rw-r--r-- 1 root wheel - 28K Jan 11 12:02 mime.types
3795 -rw-r--r-- 1 root wheel - 11K Jan 11 12:02 ssl.conf
3806 ## Starting Services
3810 It is common for a system to host a number of services. These may be started in several different fashions, each having different advantages.
3814 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.
3817 A generic startup script in `/usr/pkg/share/examples/rc.d` looks like:
3839 kill -9 `cat /var/run/foobar.pid`
3846 echo "Usage: `basename $0` {start|stop}" >&2
3863 <!-- XXX: I don't think we actually look in /usr/pkg/share/examples/rc.d -->
3865 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§ion=1) as shown below:
3871 # chmod 755 "FooBar.sh"
3877 Some services expect to be invoked by [inetd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=inetd§ion=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§ion=8) for details on editing this file.
3881 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.
3885 **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.
3889 It is also possible to use the [cron(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=cron§ion=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§ion=8) runs these processes as the owner of the `crontab`, services may be started and maintained by non-`root` users.
3893 This takes advantage of a feature of [cron(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=cron§ion=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§ion=8) is started shortly after system boot.
3903 CategoryHandbook-configuration
3911 ## Configuring the cron Utility
3913 <!-- XXX: can't really comment on this. someone please revise it -->
3916 ***Contributed by Tom Rhodes. ***
3920 One of the most useful utilities in DragonFly is [cron(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=cron§ion=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.
3924 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.
3928 **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.
3932 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`.
3936 Let us take a look at the `/etc/crontab` file (the system crontab):
3942 # /etc/crontab - root's crontab for DragonFly
3952 PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin (2)
3960 #minute hour mday month wday who command (3)
3967 */5 * * * * root /usr/libexec/atrun (4)
3973 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.
3977 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.
3981 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.
3985 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§ion=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.
3989 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.
3993 ### Installing a Crontab
3997 **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.
4001 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:
4007 % crontab crontab-file
4013 In this example, `crontab-file` is the filename of a `crontab` that was previously created.
4017 There is also an option to list installed `crontab` files: just pass the `-l` option to `crontab` and look over the output.
4021 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.
4025 If you later want to remove your user `crontab` completely, use `crontab` with the `-r` option.
4035 CategoryHandbook-configuration
4041 ## 6.7 Using rc under DragonFly
4045 ***Contributed by Tom Rhodes. ***
4049 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§ion=8&manpath=OpenBSD+3.3) can be restarted with the following command:
4055 # /etc/rc.d/sshd restart
4061 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§ion=5). For example, enabling the Network Address Translation daemon at startup is as simple as adding the following line to `/etc/rc.conf`:
4068 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.
4071 Another way to add services to the automatic startup/shutdown is to type, for example for `natd`,
4076 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:
4082 # /etc/rc.d/sshd forcerestart
4088 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:
4094 # /etc/rc.d/sshd rcvar
4104 **Note:** The second line (`# sshd`) is the output from the `rc.d` script, not a `root` prompt.
4108 To determine if a service is running, a `status` option is available. For instance to verify that `sshd` is actually started:
4114 # /etc/rc.d/sshd status
4116 sshd is running as pid 433.
4122 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.
4126 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.
4130 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§ion=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:
4135 * `PROVIDE`: Specifies the services this file provides.
4138 * `REQUIRE`: Lists services which are required for this service. This file will run ***after*** the specified services.
4141 * `BEFORE`: Lists services which depend on this service. This file will run ***before*** the specified services.
4144 * KEYWORD: When [rcorder(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rcorder§ion=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.
4146 With the `-s` option, [rcorder(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rcorder§ion=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.
4150 By using this method, an administrator can easily control system services without the hassle of ***runlevels*** like some other UNIX® operating systems.
4154 Additional information about the DragonFly `rc.d` system can be found in the [rc(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rc§ion=8), [rc.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=rc.conf§ion=5), and [rc.subr(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rc.subr§ion=8) manual pages.
4156 ### Using DragonFly's rcrun(8)
4158 Besides the methods described above DragonFly supports [rcrun(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rcrun§ion=8) to control rc(8) scripts. [rcrun(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rcrun§ion=8) provides a number of command for controlling rc(8)
4160 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.
4164 The remaining commands are:
4169 **disable** | Sets the corresponding `_enable` variable in rc.conf(5) to ***NO*** and runs the stop command.
4170 **enable** | Sets the corresponding `_enable` variable in rc.conf(5) to ***YES*** and runs the start command.
4171 **list** | Shows the status of the specified scripts. If no argument is specified, the status of all scripts is shown. |
4176 To enable the [dntpd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=dntpd§ion=8) service, you can use:
4182 To check if [dntpd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=dntpd§ion=8) is running you can use the following command:
4192 To start [dntpd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=dntpd§ion=8):
4200 Running /etc/rc.d/dntpd start
4206 Restart and stop works the same way:
4226 If a service is not enabled in `/etc/rc.conf`, but you want it start anyway, execute the following:
4232 Running /etc/rc.d/dntpd forcestart
4243 <tablestyle="width:100%"> [(1)](configtuning-rcng.html#AEN4751) | Previously this was used to define *BSD dependent features.
4254 ## 6.8 Setting Up Network Interface Cards
4258 ***Contributed by Marc Fonvieille. ***
4262 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.
4266 ### 6.8.1 Locating the Correct Driver
4270 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.
4274 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.
4278 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:
4284 dc0: <82c169 PNIC 10/100BaseTX> port 0xa000-0xa0ff mem 0xd3800000-0xd38
4286 000ff irq 15 at device 11.0 on pci0
4288 dc0: Ethernet address: 00:a0:cc:da:da:da
4290 miibus0: <MII bus> on dc0
4292 ukphy0: <Generic IEEE 802.3u media interface> on miibus0
4294 ukphy0: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto
4296 dc1: <82c169 PNIC 10/100BaseTX> port 0x9800-0x98ff mem 0xd3000000-0xd30
4298 000ff irq 11 at device 12.0 on pci0
4300 dc1: Ethernet address: 00:a0:cc:da:da:db
4302 miibus1: <MII bus> on dc1
4304 ukphy1: <Generic IEEE 802.3u media interface> on miibus1
4306 ukphy1: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto
4312 In this example, we see that two cards using the [dc(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=dc§ion=4) driver are present on the system.
4316 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§ion=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§ion=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.
4320 ### 6.8.2 Configuring the Network Card
4324 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.
4328 To display the configuration for the network interfaces on your system, enter the following command:
4336 dc0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
4338 inet 192.168.1.3 netmask 0xffffff00 broadcast 192.168.1.255
4340 ether 00:a0:cc:da:da:da
4342 media: Ethernet autoselect (100baseTX <full-duplex>)
4346 dc1: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
4348 inet 10.0.0.1 netmask 0xffffff00 broadcast 10.0.0.255
4350 ether 00:a0:cc:da:da:db
4352 media: Ethernet 10baseT/UTP
4356 lp0: flags=8810<POINTOPOINT,SIMPLEX,MULTICAST> mtu 1500
4358 lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> mtu 16384
4360 inet 127.0.0.1 netmask 0xff000000
4362 tun0: flags=8010<POINTOPOINT,MULTICAST> mtu 1500
4368 **Note:** Note that entries concerning IPv6 (`inet6` etc.) were omitted in this example.
4372 In this example, the following devices were displayed:
4377 * `dc0`: The first Ethernet interface
4380 * `dc1`: The second Ethernet interface
4383 * `lp0`: The parallel port interface
4386 * `lo0`: The loopback device
4389 * `tun0`: The tunnel device used by **ppp**
4393 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§ion=4) driver.
4397 In this example, the `dc0` device is up and running. The key indicators are:
4401 1. `UP` means that the card is configured and ready.
4403 1. The card has an Internet (`inet`) address (in this case `192.168.1.3`).
4405 1. It has a valid subnet mask (`netmask`; `0xffffff00` is the same as `255.255.255.0`).
4407 1. It has a valid broadcast address (in this case, `192.168.1.255`).
4409 1. The MAC address of the card (`ether`) is `00:a0:cc:da:da:da`
4411 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.
4413 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.
4417 If the [ifconfig(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=ifconfig§ion=8) output had shown something similar to:
4423 dc0: flags=8843<BROADCAST,SIMPLEX,MULTICAST> mtu 1500
4425 ether 00:a0:cc:da:da:da
4431 it would indicate the card has not been configured.
4435 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§ion=8) as root.
4441 # ifconfig dc0 inet 192.168.1.3 netmask 255.255.255.0
4447 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.
4451 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:
4457 ifconfig_dc0="inet 192.168.1.3 netmask 255.255.255.0"
4459 ifconfig_dc1="inet 10.0.0.1 netmask 255.255.255.0 media 10baseT/UTP"
4465 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§ion8) manual pages for more details about the allowed options and also [rc.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=rc.conf§ion=5) manual page for more information on the syntax of `/etc/rc.conf`.
4469 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.
4473 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§ion=5) and to `/usr/share/examples/etc/hosts`.
4477 ### 6.8.3 Testing and Troubleshooting
4481 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.
4485 Once the system has been rebooted, you should test the network interfaces.
4489 #### 6.8.3.1 Testing the Ethernet Card
4493 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.
4497 First test the local interface:
4503 % ping -c5 192.168.1.3
4505 PING 192.168.1.3 (192.168.1.3): 56 data bytes
4507 64 bytes from 192.168.1.3: icmp_seq#0 ttl64 time=0.082 ms
4509 64 bytes from 192.168.1.3: icmp_seq#1 ttl64 time=0.074 ms
4511 64 bytes from 192.168.1.3: icmp_seq#2 ttl64 time=0.076 ms
4513 64 bytes from 192.168.1.3: icmp_seq#3 ttl64 time=0.108 ms
4515 64 bytes from 192.168.1.3: icmp_seq#4 ttl64 time=0.076 ms
4519 --- 192.168.1.3 ping statistics ---
4521 5 packets transmitted, 5 packets received, 0% packet loss
4523 round-trip min/avg/max/stddev = 0.074/0.083/0.108/0.013 ms
4529 Now we have to ping another machine on the LAN:
4535 % ping -c5 192.168.1.2
4537 PING 192.168.1.2 (192.168.1.2): 56 data bytes
4539 64 bytes from 192.168.1.2: icmp_seq#0 ttl64 time=0.726 ms
4541 64 bytes from 192.168.1.2: icmp_seq#1 ttl64 time=0.766 ms
4543 64 bytes from 192.168.1.2: icmp_seq#2 ttl64 time=0.700 ms
4545 64 bytes from 192.168.1.2: icmp_seq#3 ttl64 time=0.747 ms
4547 64 bytes from 192.168.1.2: icmp_seq#4 ttl64 time=0.704 ms
4551 --- 192.168.1.2 ping statistics ---
4553 5 packets transmitted, 5 packets received, 0% packet loss
4555 round-trip min/avg/max/stddev = 0.700/0.729/0.766/0.025 ms
4561 You could also use the machine name instead of `192.168.1.2` if you have set up the `/etc/hosts` file.
4565 #### 6.8.3.2 Troubleshooting
4569 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.
4573 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§ion=7) manual page. You can also check the network configuration as incorrect network settings can cause slow connections.
4577 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.
4581 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.
4585 ***`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].
4589 ***`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.
4593 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§ion=7) manual page.
4603 CategoryHandbook-configuration
4612 ## 6.9 Virtual Hosts
4616 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.
4620 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`.
4624 An alias entry for the interface `fxp0` looks like:
4630 ifconfig_fxp0_alias0="inet xxx.xxx.xxx.xxx netmask xxx.xxx.xxx.xxx"
4636 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.
4640 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`).
4644 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`.
4648 The following entries configure the adapter correctly for this arrangement:
4654 ifconfig_fxp0="inet 10.1.1.1 netmask 255.255.255.0"
4656 ifconfig_fxp0_alias0="inet 10.1.1.2 netmask 255.255.255.255"
4658 ifconfig_fxp0_alias1="inet 10.1.1.3 netmask 255.255.255.255"
4660 ifconfig_fxp0_alias2="inet 10.1.1.4 netmask 255.255.255.255"
4662 ifconfig_fxp0_alias3="inet 10.1.1.5 netmask 255.255.255.255"
4664 ifconfig_fxp0_alias4="inet 202.0.75.17 netmask 255.255.255.240"
4666 ifconfig_fxp0_alias5="inet 202.0.75.18 netmask 255.255.255.255"
4668 ifconfig_fxp0_alias6="inet 202.0.75.19 netmask 255.255.255.255"
4670 ifconfig_fxp0_alias7="inet 202.0.75.20 netmask 255.255.255.255"
4682 CategoryHandbook-configuration
4689 ## 6.10 Configuration Files
4691 ### 6.10.1 /etc Layout
4693 There are a number of directories in which configuration information is kept. These include:
4696 `/etc` | Generic system configuration information; data here is system-specific.
4697 `/etc/defaults` | Default versions of system configuration files.
4698 `/etc/mail` | Extra [sendmail(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=sendmail§ion=8) configuration, other MTA configuration files.
4699 `/etc/ppp` | Configuration for both user- and kernel-ppp programs.
4700 `/etc/namedb` | Default location for [named(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=named§ion=8) data. Normally `named.conf` and zone files are stored here.
4701 `/usr/local/etc` | Configuration files for installed applications. May contain per-application subdirectories.
4702 `/usr/local/etc/rc.d` | Start/stop scripts for installed applications.
4703 `/var/db` | Automatically generated system-specific database files, such as the package database, the locate database, and so on |
4709 ### 6.10.2 Hostnames
4711 #### 6.10.2.1 /etc/resolv.conf
4713 `/etc/resolv.conf` dictates how DragonFly's resolver accesses the Internet Domain Name System (DNS).
4717 The most common entries to `resolv.conf` are:
4720 `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.
4721 `search` | Search list for hostname lookup. This is normally determined by the domain of the local hostname.
4722 `domain` | The local domain name. |
4728 A typical `resolv.conf`:
4736 nameserver 147.11.1.11
4738 nameserver 147.11.100.30
4742 **Note:** Only one of the `search` and `domain` options should be used.
4746 If you are using DHCP, [dhclient(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=dhclient§ion=8) usually rewrites `resolv.conf` with information received from the DHCP server.
4750 #### 6.10.2.2 /etc/hosts
4752 `/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§ion=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.
4764 # This file should contain the addresses and aliases
4766 # for local hosts that share this file.
4768 # In the presence of the domain name service or NIS, this file may
4770 # not be consulted at all; see /etc/nsswitch.conf for the resolution order.
4776 ::1 localhost localhost.my.domain myname.my.domain
4778 127.0.0.1 localhost localhost.my.domain myname.my.domain
4782 # Imaginary network.
4784 #10.0.0.2 myname.my.domain myname
4786 #10.0.0.3 myfriend.my.domain myfriend
4790 # According to RFC 1918, you can use the following IP networks for
4792 # private nets which will never be connected to the Internet:
4796 # 10.0.0.0 - 10.255.255.255
4798 # 172.16.0.0 - 172.31.255.255
4800 # 192.168.0.0 - 192.168.255.255
4804 # In case you want to be able to connect to the Internet, you need
4806 # real official assigned numbers. PLEASE PLEASE PLEASE do not try
4808 # to invent your own network numbers but instead get one from your
4810 # network provider (if any) or from the Internet Registry (ftp to
4812 # rs.internic.net, directory `/templates').
4818 `/etc/hosts` takes on the simple format of:
4824 [Internet address] [official hostname] [alias1] [alias2] ...
4834 10.0.0.1 myRealHostname.example.com myRealHostname foobar1 foobar2
4838 Consult [hosts(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=hosts§ion=5) for more information.
4842 ### 6.10.3 Log File Configuration
4844 #### 6.10.3.1 syslog.conf
4846 `syslog.conf` is the configuration file for the [syslogd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=syslogd§ion=8) program. It indicates which types of `syslog` messages are logged to particular log files.
4856 # Spaces ARE valid field separators in this file. However,
4858 # other *nix-like systems still insist on using tabs as field
4860 # separators. If you are sharing this file between systems, you
4862 # may want to use only tabs as field separators here.
4864 # Consult the syslog.conf(5) manual page.
4867 *.err;kern.debug;auth.notice;mail.crit /dev/console
4869 *.notice;kern.debug;lpr.info;mail.crit;news.err /var/log/messages
4872 security.* /var/log/security
4874 mail.info /var/log/maillog
4876 lpr.info /var/log/lpd-errs
4878 cron.* /var/log/cron
4883 *.notice;news.err root
4890 # uncomment this to log all writes to /dev/console to /var/log/console.log
4892 #console.info /var/log/console.log
4894 # uncomment this to enable logging of all log messages to /var/log/all.log
4896 #*.* /var/log/all.log
4898 # uncomment this to enable logging to a remote log host named loghost
4902 # uncomment these if you're running inn
4904 # news.crit /var/log/news/news.crit
4906 # news.err /var/log/news/news.err
4908 # news.notice /var/log/news/news.notice
4913 *.* /var/log/slip.log
4918 *.* /var/log/ppp.log
4922 Consult the [syslog.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=syslog.conf§ion=5) manual page for more information.
4926 #### 6.10.3.2 newsyslog.conf
4928 `newsyslog.conf` is the configuration file for [newsyslog(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=newsyslog§ion=8), a program that is normally scheduled to run by [cron(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=cron§ion=8). [newsyslog(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=newsyslog§ion=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§ion=1) format causing them to be named: `logfile.0.gz`, `logfile.1.gz`, and so on.
4932 `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.
4938 # configuration file for newsyslog
4944 # filename [owner:group] mode count size when [ZB] [/pid_file] [sig_num]
4946 /var/log/cron 600 3 100 * Z
4948 /var/log/amd.log 644 7 100 * Z
4950 /var/log/kerberos.log 644 7 100 * Z
4952 /var/log/lpd-errs 644 7 100 * Z
4954 /var/log/maillog 644 7 * @T00 Z
4956 /var/log/sendmail.st 644 10 * 168 B
4958 /var/log/messages 644 5 100 * Z
4960 /var/log/all.log 600 7 * @T00 Z
4962 /var/log/slip.log 600 3 100 * Z
4964 /var/log/ppp.log 600 3 100 * Z
4966 /var/log/security 600 10 100 * Z
4968 /var/log/wtmp 644 3 * @01T05 B
4970 /var/log/daily.log 640 7 * @T00 Z
4972 /var/log/weekly.log 640 5 1 $W6D0 Z
4974 /var/log/monthly.log 640 12 * $M1D0 Z
4976 /var/log/console.log 640 5 100 * Z
4980 Consult the [newsyslog(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=newsyslog§ion=8) manual page for more information.
4984 ### 6.10.4 sysctl.conf
4986 `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.
4990 A sample `sysctl.conf` turning off logging of fatal signal exits and letting Linux programs know they are really running under DragonFly:
4996 kern.logsigexit=0 # Do not log fatal signal exits (e.g. sig 11)
4998 compat.linux.osname=DragonFly
5000 compat.linux.osrelease=4.3-STABLE
5010 ## 6.11 Tuning with sysctl
5014 [sysctl(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=sysctl§ion=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§ion=8).
5018 At its core, [sysctl(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=sysctl§ion=8) serves two functions: to read and to modify system settings.
5022 To view all readable variables:
5034 To read a particular variable, for example, `kern.maxproc`:
5040 % sysctl kern.maxproc
5048 To set a particular variable, use the intuitive `***variable***`=`***value***` syntax:
5054 # sysctl kern.maxfiles=5000
5056 kern.maxfiles: 2088 -< 5000
5062 Settings of sysctl variables are usually either strings, numbers, or booleans (a boolean being `1` for yes or a `0` for no).
5066 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§ion=5) manual page and the [configtuning-configfiles.html#CONFIGTUNING-SYSCTLCONF Section 6.10.4].
5070 ### 6.11.1 sysctl(8) Read-only
5074 ***Contributed by Tom Rhodes. ***
5078 In some cases it may be desirable to modify read-only [sysctl(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=sysctl§ion=8) values. While this is not recommended, it is also sometimes unavoidable.
5082 For instance on some laptop models the [cardbus(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=cardbus§ion=4) device will not probe memory ranges, and fail with errors which look similar to:
5088 cbb0: Could not map register memory
5090 device_probe_and_attach: cbb0 attach returned 12
5096 Cases like the one above usually require the modification of some default [sysctl(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=sysctl§ion=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§ion=8) ***OIDs*** in their local `/boot/loader.conf`. Default settings are located in the `/boot/defaults/loader.conf` file.
5100 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§ion=4) will work properly.
5110 CategoryHandbook-configuration
5119 ## 6.12 Tuning Disks
5123 ### 6.12.1 Sysctl Variables
5127 #### 6.12.1.1 `vfs.vmiodirenable`
5131 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.
5135 #### 6.12.1.2 `vfs.write_behind`
5139 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.
5143 #### 6.12.1.3 `vfs.hirunningspace`
5147 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.
5151 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.
5155 #### 6.12.1.4 `vm.swap_idle_enabled`
5159 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.
5163 #### 6.12.1.5 `hw.ata.wc`
5167 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.
5171 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.
5175 For more information, please see [ata(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=ata§ion=4) manual page.
5177 <!-- XXX: add some more sysctls, e.g. relating to AHCI, nata, ... -->
5181 ### 6.12.2 Soft Updates
5183 **Note** that soft updates are only available on UFS.
5185 The [tunefs(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=tunefs§ion=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:
5191 # tunefs -n enable /filesystem
5193 # tunefs -n disable /filesystem
5199 A filesystem cannot be modified with [tunefs(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=tunefs§ion=8) while it is mounted. A good time to enable Soft Updates is before any partitions have been mounted, in single-user mode.
5203 **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§ion=8).
5207 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.
5211 #### 6.12.2.1 More Details about Soft Updates
5212 <!-- XXX: consider axing this section -->
5215 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.)
5219 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§ion8) 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`).
5223 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§ion8) on it and restore it from backup.
5227 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.
5231 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§ion8) 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§ion=8) needs to be run at a later time.
5235 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.
5245 CategoryHandbook-configuration
5257 ## 6.13 Tuning Kernel Limits
5261 ### 6.13.1 File/Process Limits
5265 #### 6.13.1.1 `kern.maxfiles`
5267 <!-- XXX: revise this section; someone who knows about it -->
5269 `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.
5273 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.
5277 `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.
5281 **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.
5285 #### 6.13.1.2 `kern.ipc.somaxconn`
5289 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§ion=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.
5293 ### 6.13.2 Network Limits
5297 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§ion=1) may be used to observe network cluster use. `kern.ipc.nmbclusters` loader tunable should be used to tune this at boot time.
5299 <!-- XXX: mention kern.ipc.mbufs sysctl -->
5302 For busy servers that make extensive use of the [sendfile(2)](http://leaf.dragonflybsd.org/cgi/web-man?command=sendfile§ion=2) system call, it may be necessary to increase the number of [sendfile(2)](http://leaf.dragonflybsd.org/cgi/web-man?command=sendfile§ion=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§ion=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.
5306 **Important:** Even though a socket has been marked as non-blocking, calling [sendfile(2)](http://leaf.dragonflybsd.org/cgi/web-man?command=sendfile§ion=2) on the non-blocking socket may result in the [sendfile(2)](http://leaf.dragonflybsd.org/cgi/web-man?command=sendfile§ion=2) call blocking until enough `struct sf_buf`'s are made available.
5310 #### 6.13.2.1 `net.inet.ip.portrange.*`
5314 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.
5318 #### 6.13.2.2 TCP Bandwidth Delay Product
5319 <!-- XXX: Revise this stuff, I'm not familiar with it -->
5322 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.
5326 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` may be beneficial. However, note that setting high minimums may effectively disable bandwidth limiting depending on the link. The limiting feature reduces the amount of data built up in intermediate route and switch packet queues as well as reduces the amount of data built up in the local host's interface queue. With fewer packets queued up, interactive connections, especially over slow modems, will also be able to operate with lower ***Round Trip Times***. However, note that this feature only effects data transmission (uploading / server side). It has no effect on data reception (downloading).
5330 Adjusting `net.inet.tcp.inflight_stab` is ***not*** recommended. This parameter defaults to 20, representing 2 maximal packets added to the bandwidth delay product window calculation. The additional window is required to stabilize the algorithm and improve responsiveness to changing conditions, but it can also result in higher ping times over slow links (though still much lower than you would get without the inflight algorithm). In such cases, you may wish to try reducing this parameter to 15, 10, or 5; and may also have to reduce `net.inet.tcp.inflight_min` (for example, to 3500) to get the desired effect. Reducing these parameters should be done as a last resort only.
5340 CategoryHandbook-configuration
5350 ## 6.14 Adding Swap Space
5354 No matter how well you plan, sometimes a system does not run as you expect. If you find you need more swap space, it is simple enough to add. You have three ways to increase swap space: adding a new hard drive, enabling swap over NFS, and creating a swap file on an existing partition.
5358 ### 6.14.1 Swap on a New Hard Drive
5362 The best way to add swap, of course, is to use this as an excuse to add another hard drive. You can always use another hard drive, after all. If you can do this, go reread the discussion about swap space in [configtuning-initial.html Section 6.2] for some suggestions on how to best arrange your swap.
5366 ### 6.14.2 Swapping over NFS
5370 Swapping over NFS is only recommended if you do not have a local hard disk to swap to. Even though DragonFly has an excellent NFS implementation, NFS swapping will be limited by the available network bandwidth and puts an additional burden on the NFS server.
5374 ### 6.14.3 Swapfiles
5378 You can create a file of a specified size to use as a swap file. In our example here we will use a 64MB file called `/usr/swap0`. You can use any name you want, of course.
5382 **Example 6-1. Creating a Swapfile**
5386 1. Be certain that your kernel configuration includes the vnode driver. It is ***not*** in recent versions of `GENERIC`.
5390 pseudo-device vn 1 #Vnode driver (turns a file into a device)
5394 1. Create a vn-device:
5404 1. Create a swapfile (`/usr/swap0`):
5408 # dd if=/dev/zero of=/usr/swap0 bs=1024k count=64
5412 1. Set proper permissions on (`/usr/swap0`):
5416 # chmod 0600 /usr/swap0
5420 1. Enable the swap file in `/etc/rc.conf`:
5424 swapfile="/usr/swap0" # Set to name of swapfile if aux swapfile desired.
5428 1. Reboot the machine or to enable the swap file immediately, type:
5432 # vnconfig -e /dev/vn0b /usr/swap0 swap
5444 CategoryHandbook-configuration
5454 ## 6.15 Power and Resource Management
5458 ***Written by Hiten Pandya and Tom Rhodes. ***
5462 It is very important to utilize hardware resources in an efficient manner. Before ACPI was introduced, it was very difficult and inflexible for operating systems to manage the power usage and thermal properties of a system. The hardware was controlled by some sort of BIOS embedded interface, such as ***Plug and Play BIOS (PNPBIOS)***, or ***Advanced Power Management (APM)*** and so on. Power and Resource Management is one of the key components of a modern operating system. For example, you may want an operating system to monitor system limits (and possibly alert you) in case your system temperature increased unexpectedly.
5466 In this section, we will provide comprehensive information about ACPI. References will be provided for further reading at the end. Please be aware that ACPI is available on DragonFly systems as a default kernel module.
5470 ### 6.15.1 What Is ACPI?
5474 Advanced Configuration and Power Interface (ACPI) is a standard written by an alliance of vendors to provide a standard interface for hardware resources and power management (hence the name). It is a key element in ***Operating System-directed configuration and Power Management***, i.e.: it provides more control and flexibility to the operating system (OS). Modern systems ***stretched*** the limits of the current Plug and Play interfaces (such as APM), prior to the introduction of ACPI. ACPI is the direct successor to APM (Advanced Power Management).
5478 ### 6.15.2 Shortcomings of Advanced Power Management (APM)
5482 The ***Advanced Power Management (APM)*** facility control's the power usage of a system based on its activity. The APM BIOS is supplied by the (system) vendor and it is specific to the hardware platform. An APM driver in the OS mediates access to the ***APM Software Interface***, which allows management of power levels.
5485 There are four major problems in APM. Firstly, power management is done by the (vendor-specific) BIOS, and the OS does not have any knowledge of it. One example of this, is when the user sets idle-time values for a hard drive in the APM BIOS, that when exceeded, it (BIOS) would spin down the hard drive, without the consent of the OS. Secondly, the APM logic is embedded in the BIOS, and it operates outside the scope of the OS. This means users can only fix problems in their APM BIOS by flashing a new one into the ROM; which, is a very dangerous procedure, and if it fails, it could leave the system in an unrecoverable state. Thirdly, APM is a vendor-specific technology, which, means that there is a lot or parity (duplication of efforts) and bugs found in one vendor's BIOS, may not be solved in others. Last but not the least, the APM BIOS did not have enough room to implement a sophisticated power policy, or one that can adapt very well to the purpose of the machine.
5488 ***Plug and Play BIOS (PNPBIOS)*** was unreliable in many situations. PNPBIOS is 16-bit technology, so the OS has to use 16-bit emulation in order to ***interface*** with PNPBIOS methods.
5492 The DragonFly APM driver is documented in the [apm(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=apm§ion=4) manual page.
5496 ### 6.15.3 Configuring ACPI
5500 The `acpi.ko` driver is loaded by default at start up by the [loader(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=loader§ion=8) and should ***not*** be compiled into the kernel. The reasoning behind this is that modules are easier to work with, say if switching to another `acpi.ko` without doing a kernel rebuild. This has the advantage of making testing easier. Another reason is that starting ACPI after a system has been brought up is not too useful, and in some cases can be fatal. In doubt, just disable ACPI all together. This driver should not and can not be unloaded because the system bus uses it for various hardware interactions. ACPI can be disabled with the [acpiconf(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=acpiconf§ion=8) utility. In fact most of the interaction with ACPI can be done via [acpiconf(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=acpiconf§ion=8). Basically this means, if anything about ACPI is in the [dmesg(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=dmesg§ion=8) output, then most likely it is already running.
5504 **Note:** ACPI and APM cannot coexist and should be used separately. The last one to load will terminate if the driver notices the other running.
5508 In the simplest form, ACPI can be used to put the system into a sleep mode with [acpiconf(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=acpiconf§ion=8), the `-s` flag, and a `1-5` option. Most users will only need `1`. Option `5` will do a soft-off which is the same action as:
5515 The other options are available. Check out the [acpiconf(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=acpiconf§ion=8) manual page for more information.
5518 ## Using and Debugging DragonFly ACPI
5522 ***Written by Nate Lawson. With contributions from Peter Schultz and Tom Rhodes. ***
5525 ACPI is a fundamentally new way of discovering devices, managing power usage, and providing standardized access to various hardware previously managed by the BIOS. Progress is being made toward ACPI working on all systems, but bugs in some motherboards ***ACPI Machine Language*** (AML) bytecode, incompleteness in DragonFly's kernel subsystems, and bugs in the Intel ACPI-CA interpreter continue to appear.
5528 This document is intended to help you assist the DragonFly ACPI maintainers in identifying the root cause of problems you observe and debugging and developing a solution. Thanks for reading this and we hope we can solve your system's problems.
5531 ### Submitting Debugging Information
5533 **Note:** Before submitting a problem, be sure you are running the latest BIOS version and, if available, embedded controller firmware version.
5535 For those of you that want to submit a problem right away, please send the following information to [bugs](http://leaf.dragonflybsd.org/mailarchive/)
5538 * Description of the buggy behavior, including system type and model and anything that causes the bug to appear. Also, please note as accurately as possible when the bug began occurring if it is new for you.
5540 * The dmesg output after ***boot `-v`***, including any error messages generated by you exercising the bug.
5542 * dmesg output from ***boot `-v`*** with ACPI disabled, if disabling it helps fix the problem.
5544 * Output from ***sysctl hw.acpi***. This is also a good way of figuring out what features your system offers.
5546 * URL where your ***ACPI Source Language*** (ASL) can be found. Do ***not*** send the ASL directly to the list as it can be very large. Generate a copy of your ASL by running this command:
5549 # acpidump -t -d > name-system.asl
5553 (Substitute your login name for `name` and manufacturer/model for `system`. Example: `njl-FooCo6000.asl`)
5561 ACPI is present in all modern computers that conform to the ia32 (x86), ia64 (Itanium), and amd64 (AMD) architectures. The full standard has many features including CPU performance management, power planes control, thermal zones, various battery systems, embedded controllers, and bus enumeration. Most systems implement less than the full standard. For instance, a desktop system usually only implements the bus enumeration parts while a laptop might have cooling and battery management support as well. Laptops also have suspend and resume, with their own associated complexity.
5565 An ACPI-compliant system has various components. The BIOS and chipset vendors provide various fixed tables (e.g., FADT) in memory that specify things like the APIC map (used for SMP), config registers, and simple configuration values. Additionally, a table of bytecode (the ***Differentiated System Description Table*** DSDT) is provided that specifies a tree-like name space of devices and methods.
5569 The ACPI driver must parse the fixed tables, implement an interpreter for the bytecode, and modify device drivers and the kernel to accept information from the ACPI subsystem. For DragonFly, Intel has provided an interpreter (ACPI-CA) that is shared with Linux and NetBSD®. The path to the ACPI-CA source code is `src/sys/dev/acpica5`. Finally, drivers that implement various ACPI devices are found in `src/sys/dev/acpica5`.
5577 For ACPI to work correctly, all the parts have to work correctly. Here are some common problems, in order of frequency of appearance, and some possible workarounds or fixes.
5585 ACPI has three suspend to RAM (STR) states, `S1`-`S3`, and one suspend to disk state (`STD`), called `S4`. `S5` is ***soft off*** and is the normal state your system is in when plugged in but not powered up. `S4` can actually be implemented two separate ways. `S4`BIOS is a BIOS-assisted suspend to disk. `S4`OS is implemented entirely by the operating system.
5589 Start by checking `sysctl` `hw.acpi` for the suspend-related items. Here are the results for my Thinkpad:
5591 hw.acpi.supported_sleep_state: S3 S4 S5
5596 This means that I can use `acpiconf -s` to test `S3`, `S4`OS, and `S5`. If `s4bios` was one (`1`), I would have `S4`BIOS support instead of `S4` OS.
5600 When testing suspend/resume, start with `S1`, if supported. This state is most likely to work since it doesn't require much driver support. No one has implemented `S2` but if you have it, it's similar to `S1`. The next thing to try is `S3`. This is the deepest STR state and requires a lot of driver support to properly reinitialize your hardware. If you have problems resuming, feel free to email the [bugs](http://leaf.dragonflybsd.org/mailarchive/) list but do not expect the problem to be resolved since there are a lot of drivers/hardware that need more testing and work.
5604 To help isolate the problem, remove as many drivers from your kernel as possible. If it works, you can narrow down which driver is the problem by loading drivers until it fails again. Typically binary drivers like `nvidia.ko`, **X11** display drivers, and USB will have the most problems while Ethernet interfaces usually work fine. If you can load/unload the drivers ok, you can automate this by putting the appropriate commands in `/etc/rc.suspend` and `/etc/rc.resume`. There is a commented-out example for unloading and loading a driver. Try setting `hw.acpi.reset_video` to zero (0) if your display is messed up after resume. Try setting longer or shorter values for `hw.acpi.sleep_delay` to see if that helps.
5608 Another thing to try is load a recent Linux distribution with ACPI support and test their suspend/resume support on the same hardware. If it works on Linux, it's likely a DragonFly driver problem and narrowing down which driver causes the problems will help us fix the problem. Note that the ACPI maintainers do not usually maintain other drivers (e.g sound, ATA, etc.) so any work done on tracking down a driver problem should probably eventually be posted to the [bugs](http://leaf.dragonflybsd.org/mailarchive/) list and mailed to the driver maintainer. If you are feeling adventurous, go ahead and start putting some debugging [printf(3)](http://leaf.dragonflybsd.org/cgi/web-man?command#printf§ion3)s in a problematic driver to track down where in its resume function it hangs.
5610 Finally, try disabling ACPI and enabling APM instead. If suspend/resume works with APM, you may be better off sticking with APM, especially on older hardware (pre-2000). It took vendors a while to get ACPI support correct and older hardware is more likely to have BIOS problems with ACPI.
5612 <-- XXX: mention sensors somewhere; but not in this section -->
5615 #### System Hangs (temporary or permanent)
5617 Most system hangs are a result of lost interrupts or an interrupt storm. Chipsets have a lot of problems based on how the BIOS configures interrupts before boot, correctness of the APIC (MADT) table, and routing of the ***System Control Interrupt*** (SCI).
5619 Interrupt storms can be distinguished from lost interrupts by checking the output of `vmstat -i` and looking at the line that has `acpi0`. If the counter is increasing at more than a couple per second, you have an interrupt storm. If the system appears hung, try breaking to DDB ( **CTRL** + **ALT** + **ESC** on console) and type `show interrupts`.
5621 Your best hope when dealing with interrupt problems is to try disabling APIC support with `hint.apic.0.disabled="1"` in `loader.conf`.
5627 Panics are relatively rare for ACPI and are the top priority to be fixed. The first step is to isolate the steps to reproduce the panic (if possible) and get a backtrace. Follow the advice for enabling `options DDB` and setting up a serial console (see [ this section](serialconsole-setup.html#SERIALCONSOLE-DDB)) or setting up a [dump(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=dump§ion=8) partition. You can get a backtrace in DDB with `tr`. If you have to handwrite the backtrace, be sure to at least get the lowest five (5) and top five (5) lines in the trace.
5629 Then, try to isolate the problem by booting with ACPI disabled. If that works, you can isolate the ACPI subsystem by using various values of `debug.acpi.disable`. See the [acpi(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=acpi§ion=4) manual page for some examples.
5633 #### System Powers Up After Suspend or Shutdown
5637 First, try setting `hw.acpi.disable_on_poweroff#0` in [loader.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=loader.conf§ion=5). This keeps ACPI from disabling various events during the shutdown process. Some systems need this value set to ***1*** (the default) for the same reason. This usually fixes the problem of a system powering up spontaneously after a suspend or poweroff.
5645 If you have other problems with ACPI (working with a docking station, devices not detected, etc.), please email a description to the mailing list as well; however, some of these issues may be related to unfinished parts of the ACPI subsystem so they might take a while to be implemented. Please be patient and prepared to test patches we may send you.
5649 ### ASL, acpidump, and IASL
5650 <!-- XXX: IMHO all this crap about fixing your DSDT etc should be axed -->
5653 The most common problem is the BIOS vendors providing incorrect (or outright buggy!) bytecode. This is usually manifested by kernel console messages like this:
5659 ACPI-1287: *** Error: Method execution failed [\\_SB_.PCI0.LPC0.FIGD._STA] \\
5661 (Node 0xc3f6d160), AE_NOT_FOUND
5667 Often, you can resolve these problems by updating your BIOS to the latest revision. Most console messages are harmless but if you have other problems like battery status not working, they're a good place to start looking for problems in the AML. The bytecode, known as AML, is compiled from a source language called ASL. The AML is found in the table known as the DSDT. To get a copy of your ASL, use [acpidump(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=acpidump§ion=8). You should use both the `-t` (show contents of the fixed tables) and `-d` (disassemble AML to ASL) options. See the [submitting Debugging Information](acpi-debug.html#ACPI-SUBMITDEBUG) section for an example syntax.
5671 The simplest first check you can do is to recompile your ASL to check for errors. Warnings can usually be ignored but errors are bugs that will usually prevent ACPI from working correctly. To recompile your ASL, issue the following command:
5686 In the long run, our goal is for almost everyone to have ACPI work without any user intervention. At this point, however, we are still developing workarounds for common mistakes made by the BIOS vendors. The Microsoft interpreter (`acpi.sys` and `acpiec.sys`) does not strictly check for adherence to the standard, and thus many BIOS vendors who only test ACPI under Windows never fix their ASL. We hope to continue to identify and document exactly what non-standard behavior is allowed by Microsoft's interpreter and replicate it so DragonFly can work without forcing users to fix the ASL. As a workaround and to help us identify behavior, you can fix the ASL manually. If this works for you, please send a [diff(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=diff§ion=1) of the old and new ASL so we can possibly work around the buggy behavior in ACPI-CA and thus make your fix unnecessary.
5689 Here is a list of common error messages, their cause, and how to fix them:
5692 #### OS dependencies
5695 Some AML assumes the world consists of various Windows versions. You can tell DragonFly to claim it is any OS to see if this fixes problems you may have. An easy way to override this is to set `hw.acpi.osname=Windows 2001` in `/boot/loader.conf` or other similar strings you find in the ASL.
5699 #### Missing Return statements
5703 Some methods do not explicitly return a value as the standard requires. While ACPI-CA does not handle this, DragonFly has a workaround that allows it to return the value implicitly. You can also add explicit Return statements where required if you know what value should be returned. To force `iasl` to compile the ASL, use the `-f` flag.
5707 #### Overriding the Default AML
5711 After you customize `your.asl`, you will want to compile it, run:
5720 You can add the `-f` flag to force creation of the AML, even if there are errors during compilation. Remember that some errors (e.g., missing Return statements) are automatically worked around by the interpreter.
5724 `DSDT.aml` is the default output filename for `iasl`. You can load this instead of your BIOS's buggy copy (which is still present in flash memory) by editing `/boot/loader.conf` as follows:
5730 acpi_dsdt_load="YES"
5732 acpi_dsdt_name="/boot/DSDT.aml"
5737 Be sure to copy your `DSDT.aml` to the `/boot` directory.
5741 ### Getting Debugging Output From ACPI
5745 The ACPI driver has a very flexible debugging facility. It allows you to specify a set of subsystems as well as the level of verbosity. The subsystems you wish to debug are specified as ***layers*** and are broken down into ACPI-CA components (ACPI_ALL_COMPONENTS) and ACPI hardware support (ACPI_ALL_DRIVERS). The verbosity of debugging output is specified as the ***level*** and ranges from ACPI_LV_ERROR (just report errors) to ACPI_LV_VERBOSE (everything). The ***level*** is a bitmask so multiple options can be set at once, separated by spaces. In practice, you will want to use a serial console to log the output if it is so long it flushes the console message buffer.
5749 Debugging output is not enabled by default. To enable it, add `options ACPI_DEBUG` to your kernel config if ACPI is compiled into the kernel. You can add `ACPI_DEBUG=1` to your `/etc/make.conf` to enable it globally. If it is a module, you can recompile just your `acpi.ko` module as follows:
5755 # cd /sys/dev/acpica5 && make clean && make ACPI_DEBUG=1
5761 Install `acpi.ko` in `/boot/kernel` and add your desired level and layer to `loader.conf`. This example enables debug messages for all ACPI-CA components and all ACPI hardware drivers (CPU, LID, etc.) It will only output error messages, the least verbose level.
5767 debug.acpi.layer="ACPI_ALL_COMPONENTS ACPI_ALL_DRIVERS"
5769 debug.acpi.level="ACPI_LV_ERROR"
5775 If the information you want is triggered by a specific event (say, a suspend and then resume), you can leave out changes to `loader.conf` and instead use `sysctl` to specify the layer and level after booting and preparing your system for the specific event. The `sysctl`s are named the same as the tunables in `loader.conf`.
5783 More information about ACPI may be found in the following locations:
5788 * The [FreeBSD ACPI mailing list](http://lists.FreeBSD.org/mailman/listinfo/freebsd-acpi) (This is FreeBSD-specific; posting DragonFly questions here may not generate much of an answer.)
5791 * The ACPI Mailing List Archives (FreeBSD) http://lists.freebsd.org/pipermail/freebsd-acpi/
5794 * The old ACPI Mailing List Archives (FreeBSD) http://home.jp.FreeBSD.org/mail-list/acpi-jp/
5797 * The ACPI 2.0 Specification http://acpi.info/spec.htm
5800 * DragonFly Manual pages: [acpidump(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=acpidump§ion8), [acpiconf(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=acpiconf§ion=8), [acpidb(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=acpidb§ion=8)
5803 * [DSDT debugging resource](http://www.cpqlinux.com/acpi-howto.html#fix_broken_dsdt). (Uses Compaq as an example but generally useful.)
5813 CategoryHandbook-configuration
5821 ## The DragonFly virtual kernels
5825 ***Obtained from [vkernel(7)](http://leaf.dragonflybsd.org/cgi/web-man?command=vkernel§ion=7) written by Sascha Wildner, added by Matthias Schmidt***
5828 The idea behind the development of the vkernel architecture was to find an elegant solution to debugging of the kernel and its components. It eases debugging, as it allows for a virtual kernel being loaded in userland and hence debug it without affecting the real kernel itself. By being able to load it on a running system it also removes the need for reboots between kernel compiles.
5830 The vkernel architecture allows for running DragonFly kernels in userland.
5834 ### Supported devices
5836 A number of virtual device drivers exist to supplement the virtual kernel.
5838 <!-- XXX: why do they only support 16 devices? is this really true? -->
5842 The vkd driver allows for up to 16 [vn(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=vn§ion=4) based disk devices. The root device will be `vkd0`.
5846 The vcd driver allows for up to 16 virtual CD-ROM devices. Basically this is a read only `vkd` device with a block size of 2048.
5848 #### Network interface
5850 The vke driver supports up to 16 virtual network interfaces which are
5852 associated with [tap(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=tap§ion=4) devices on the host. For each `vke` device, the per-interface read only [sysctl(3)](http://leaf.dragonflybsd.org/cgi/web-man?command=sysctl§ion=3) variable `hw.vkeX.tap_unit` holds the unit number of the associated [tap(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=tap§ion=4) device.
5859 ## Setup a virtual kernel environment
5863 A couple of steps are necessary in order to prepare the system to build and run a virtual kernel.
5865 ### Setting up the filesystem
5867 The vkernel architecture needs a number of files which reside in `/var/vkernel`. Since these files tend to get rather big and the `/var` partition is usually of limited size, we recommend the directory to be created in the `/home` partition with a link to it in `/var`:
5871 % mkdir /home/var.vkernel
5872 % ln -s /home/var.vkernel /var/vkernel
5874 Next, a filesystem image to be used by the virtual kernel has to be created and populated (assuming world has been built previously):
5876 # dd if=/dev/zero of=/var/vkernel/rootimg.01 bs=1m count=2048
5877 # vnconfig -c vn0 /var/vkernel/rootimg.01
5878 # disklabel -r -w vn0s0 auto
5879 # disklabel -e vn0s0 # add 'a' partition with fstype `4.2BSD' size could be '*'
5881 # mount /dev/vn0s0a /mnt
5883 If instead of using `vn0` you specify `vn` to `vnconfig`, a new `vn` device will be created and a message saying which `vnX` was created will appear. This effectively lifts the limit of 4 vn devices.
5885 Assuming that you build your world before, you can populate the image now. If you didn't build your world see [chapter 21](../updating-makeworld.html).
5888 # make installworld DESTDIR=/mnt
5890 # make distribution DESTDIR=/mnt
5893 Create a fstab file to let the vkernel find your image file.
5897 # echo '/dev/vkd0s0a / ufs rw 1 1' >/mnt/etc/fstab
5898 # echo 'proc /proc procfs rw 0 0' >>/mnt/etc/fstab
5901 Edit `/mnt/etc/ttys` and replace the console entry with the following line and turn off all other gettys.
5903 # console "/usr/libexec/getty Pc" cons25 on secure
5906 Then, unmount the disk.
5913 ### Compiling the virtual kernel
5915 In order to compile a virtual kernel use the VKERNEL kernel configuration file residing in `/usr/src/sys/config` (or a configuration file derived thereof):
5919 # make -DNO_MODULES buildkernel KERNCONF=VKERNEL
5920 # make -DNO_MODULES installkernel KERNCONF=VKERNEL DESTDIR=/var/vkernel
5924 ### Enabling virtual kernel operation
5926 A special sysctl(8), `vm.vkernel_enable`, must be set to enable vkernel operation:
5928 # sysctl vm.vkernel_enable=1
5931 To make this change permanent, edit `/etc/sysctl.conf`
5940 ### Configuring the network on the host system
5942 In order to access a network interface of the host system from the vkernel, you must add the interface to a [bridge(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=bridge§ion=4) device which will then be passed to the `-I` option:
5946 # kldload if_bridge.ko
5948 # ifconfig bridge0 create
5949 # ifconfig bridge0 addm re0 # assuming re0 is the host's interface
5950 # ifconfig bridge0 up
5954 **Note** : You have to change `re0` to the interface of your host machine.
5959 ## Run a virtual kernel
5963 Finally, the virtual kernel can be run:
5966 # ./boot/kernel -m 64m -r /var/vkernel/rootimg.01 -I auto:bridge0
5968 You can issue the reboot(8), halt(8), or shutdown(8) commands from inside a virtual kernel. After doing a clean shutdown the reboot(8) command will re-exec the virtual kernel binary while the other two will cause the virtual kernel to exit.
5982 ## Chapter 7 The DragonFly Booting Process
5991 The process of starting a computer and loading the operating system is referred to as ***the bootstrap process***, or simply ***booting***. DragonFly's boot process provides a great deal of flexibility in customizing what happens when you start the system, allowing you to select from different operating systems installed on the same computer, or even different versions of the same operating system or installed kernel.
5995 This chapter details the configuration options you can set and how to customize the DragonFly boot process. This includes everything that happens until the DragonFly kernel has started, probed for devices, and started [init(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#init§ion8). If you are not quite sure when this happens, it occurs when the text color changes from bright white to grey.
5999 After reading this chapter, you will know:
6003 * What the components of the DragonFly bootstrap system are, and how they interact.
6005 * The options you can give to the components in the DragonFly bootstrap to control the boot process.
6007 * The basics of [device.hints(5)](http://leaf.dragonflybsd.org/cgi/web-man?command#device.hints§ion5&manpath=FreeBSD+5.2-current).
6010 **x86 Only:** This chapter only describes the boot process for DragonFly running on x86 systems.
6029 ## 7.2 The Booting Problem
6032 Turning on a computer and starting the operating system poses an interesting dilemma. By definition, the computer does not know how to do anything until the operating system is started. This includes running programs from the disk. So if the computer can not run a program from the disk without the operating system, and the operating system programs are on the disk, how is the operating system started?
6035 This problem parallels one in the book ***The Adventures of Baron Munchausen***. A character had fallen part way down a manhole, and pulled himself out by grabbing his bootstraps, and lifting. In the early days of computing the term ***bootstrap*** was applied to the mechanism used to load the operating system, which has become shortened to ***booting***.
6038 On x86 hardware the Basic Input/Output System (BIOS) is responsible for loading the operating system. To do this, the BIOS looks on the hard disk for the Master Boot Record (MBR), which must be located on a specific place on the disk. The BIOS has enough knowledge to load and run the MBR, and assumes that the MBR can then carry out the rest of the tasks involved in loading the operating system possibly with the help of the BIOS.
6041 The code within the MBR is usually referred to as a ***boot manager***, especially when it interacts with the user. In this case the boot manager usually has more code in the first ***track*** of the disk or within some OS's file system. (A boot manager is sometimes also called a ***boot loader***, but FreeBSD uses that term for a later stage of booting.) Popular boot managers include **boot0** (a.k.a. **Boot Easy** , the standard DragonFly boot manager), **Grub** , **GAG** , and **LILO** . (Only **boot0** fits within the MBR.)
6044 If you have only one operating system installed on your disks then a standard PC MBR will suffice. This MBR searches for the first bootable (a.k.a. active) slice on the disk, and then runs the code on that slice to load the remainder of the operating system. The MBR installed by [fdisk(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=fdisk§ion=8), by default, is such an MBR. It is based on `/boot/mbr`.
6047 If you have installed multiple operating systems on your disks then you can install a different boot manager, one that can display a list of different operating systems, and allows you to choose the one to boot from. Two of these are discussed in the next subsection.
6050 The remainder of the DragonFly bootstrap system is divided into three stages. The first stage is run by the MBR, which knows just enough to get the computer into a specific state and run the second stage. The second stage can do a little bit more, before running the third stage. The third stage finishes the task of loading the operating system. The work is split into these three stages because the PC standards put limits on the size of the programs that can be run at stages one and two. Chaining the tasks together allows DragonFly to provide a more flexible loader.
6053 The kernel is then started and it begins to probe for devices and initialize them for use. Once the kernel boot process is finished, the kernel passes control to the user process [init(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=init§ion=8), which then makes sure the disks are in a usable state. [init(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=init§ion=8) then starts the user-level resource configuration which mounts file systems, sets up network cards to communicate on the network, and generally starts all the processes that usually are run on a DragonFly system at startup.
6063 CategoryHandbook-booting
6072 ## 7.3 The Boot Manager and Boot Stages
6076 ### 7.3.1 The Boot Manager
6080 The code in the MBR or boot manager is sometimes referred to as ***stage zero*** of the boot process. This subsection discusses two of the boot managers previously mentioned: **boot0** and **LILO** .
6084 **The** boot0 ** Boot Manager:** The MBR installed by FreeBSD's installer or [boot0cfg(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=boot0cfg§ion=8), by default, is based on `/boot/boot0`. (The **boot0** program is very simple, since the program in the MBR can only be 446 bytes long because of the slice table and `0x55AA` identifier at the end of the MBR.) If you have installed **boot0** and multiple operating systems on your hard disks, then you will see a display similar to this one at boot time:
6088 **Example 7-1. `boot0` Screenshot**
6112 Other operating systems, in particular Windows®, have been known to overwrite an existing MBR with their own. If this happens to you, or you want to replace your existing MBR with the DragonFly MBR then use the following command:
6118 # fdisk -B -b /boot/boot0 device
6124 where `***device***` is the device that you boot from, such as `ad0` for the first IDE disk, `ad2` for the first IDE disk on a second IDE controller, `da0` for the first SCSI disk, and so on. Or, if you want a custom configuration of the MBR, use [boot0cfg(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=boot0cfg§ion=8).
6128 **The LILO Boot Manager:** To install this boot manager so it will also boot DragonFly, first start Linux and add the following to your existing `/etc/lilo.conf` configuration file:
6138 loader=/boot/chain.b
6146 In the above, specify DragonFly's primary partition and drive using Linux specifiers, replacing `***X***` with the Linux drive letter and `***Y***` with the Linux primary partition number. If you are using a SCSI drive, you will need to change `***/dev/hd***` to read something similar to `***/dev/sd***`. The `loader=/boot/chain.b` line can be omitted if you have both operating systems on the same drive. Now run `/sbin/lilo -v` to commit your new changes to the system; this should be verified by checking its screen messages.
6150 ### 7.3.2 Stage One, /boot/boot1, and Stage Two, /boot/boot2
6154 Conceptually the first and second stages are part of the same program, on the same area of the disk. Because of space constraints they have been split into two, but you would always install them together. They are copied from the combined file `/boot/boot` by the installer or **disklabel** (see below).
6158 They are located outside file systems, in the first track of the boot slice, starting with the first sector. This is where [ boot0](boot-blocks.html#BOOT-BOOT0), or any other boot manager, expects to find a program to run which will continue the boot process. The number of sectors used is easily determined from the size of `/boot/boot`.
6162 They are found on the boot sector of the boot slice, which is where [ boot0](boot-blocks.html#BOOT-BOOT0), or any other program on the MBR expects to find the program to run to continue the boot process. The files in the `/boot` directory are copies of the real files, which are stored outside of the DragonFly file system.
6166 `boot1` is very simple, since it can only be 512 bytes in size, and knows just enough about the DragonFly ***disklabel***, which stores information about the slice, to find and execute `boot2`.
6170 `boot2` is slightly more sophisticated, and understands the DragonFly file system enough to find files on it, and can provide a simple interface to choose the kernel or loader to run.
6174 Since the [ loader](boot-blocks.html#BOOT-LOADER) is much more sophisticated, and provides a nice easy-to-use boot configuration, `boot2` usually runs it, but previously it was tasked to run the kernel directly.
6178 **Example 7-2. boot2 Screenshot**
6184 >> DragonFly/i386 BOOT
6186 Default: 0:ad(0,a)/boot/loader
6194 If you ever need to replace the installed `boot1` and `boot2` use [disklabel(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel§ion=8):
6200 # disklabel -B diskslice
6206 where `***diskslice***` is the disk and slice you boot from, such as `ad0s1` for the first slice on the first IDE disk.
6210 ### 7.3.3 Stage Three, `/boot/loader`
6214 The loader is the final stage of the three-stage bootstrap, and is located on the file system, usually as `/boot/loader`.
6218 The loader is intended as a user-friendly method for configuration, using an easy-to-use built-in command set, backed up by a more powerful interpreter, with a more complex command set.
6222 #### 7.3.3.1 Loader Program Flow
6226 During initialization, the loader will probe for a console and for disks, and figure out what disk it is booting from. It will set variables accordingly, and an interpreter is started where user commands can be passed from a script or interactively.
6230 The loader will then read `/boot/loader.rc`, which by default reads in `/boot/defaults/loader.conf` which sets reasonable defaults for variables and reads `/boot/loader.conf` for local changes to those variables. `loader.rc` then acts on these variables, loading whichever modules and kernel are selected.
6234 Finally, by default, the loader issues a 10 second wait for key presses, and boots the kernel if it is not interrupted. If interrupted, the user is presented with a prompt which understands the easy-to-use command set, where the user may adjust variables, unload all modules, load modules, and then finally boot or reboot.
6238 #### 7.3.3.2 Loader Built-In Commands
6242 These are the most commonly used loader commands. For a complete discussion of all available commands, please see [loader(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=loader§ion=8).
6246 * autoboot `***seconds***`: Proceeds to boot the kernel if not interrupted within the time span given, in seconds. It displays a countdown, and the default time span is 10 seconds.
6248 * boot [`***-options***`] [`***kernelname***`]: Immediately proceeds to boot the kernel, with the given options, if any, and with the kernel name given, if it is.
6250 *boot-conf: Goes through the same automatic configuration of modules based on variables as what happens at boot. This only makes sense if you use `unload` first, and change some variables, most commonly `kernel`.
6252 * help [`***topic***`]: Shows help messages read from `/boot/loader.help`. If the topic given is `index`, then the list of available topics is given.
6254 * include `***filename***` ...: Processes the file with the given filename. The file is read in, and interpreted line by line. An error immediately stops the include command.
6256 * load [`-t` `***type***`] `***filename***`: Loads the kernel, kernel module, or file of the type given, with the filename given. Any arguments after filename are passed to the file.
6258 * ls [`-l`] [`***path***`]: Displays a listing of files in the given path, or the root directory, if the path is not specified. If `-l` is specified, file sizes will be shown too.
6260 * lsdev [`-v`]: Lists all of the devices from which it may be possible to load modules. If `-v` is specified, more details are printed.
6262 * lsmod [`-v`]: Displays loaded modules. If `-v` is specified, more details are shown.
6264 * more `***filename***`: Displays the files specified, with a pause at each `LINES` displayed.
6266 * reboot: Immediately reboots the system.
6268 * set `***variable***`, set `***variable***`=`***value***`: Sets the loader's environment variables.
6270 * unload: Removes all loaded modules.
6274 #### 7.3.3.3 Loader Examples
6278 Here are some practical examples of loader usage:
6283 * To simply boot your usual kernel, but in single-user mode:
6292 * To unload your usual kernel and modules, and then load just your old (or another) kernel:
6302 You can use `kernel.GENERIC` to refer to the generic kernel that comes on the install disk, or `kernel.old` to refer to your previously installed kernel (when you have upgraded or configured your own kernel, for example).
6304 **Note:** Use the following to load your usual modules with another kernel:
6310 set kernel="kernel.old"
6317 * To load a kernel configuration script (an automated script which does the things you would normally do in the kernel boot-time configurator):
6321 load -t userconfig_script /boot/kernel.conf
6333 ## 7.4 Kernel Interaction During Boot
6337 Once the kernel is loaded by either [ loader](boot-blocks.html#BOOT-LOADER) (as usual) or [ boot2](boot-blocks.html#BOOT-BOOT1) (bypassing the loader), it examines its boot flags, if any, and adjusts its behavior as necessary.
6341 ### 7.4.1 Kernel Boot Flags
6345 Here are the more common boot flags:
6349 `-a`:: during kernel initialization, ask for the device to mount as the root file system.`-C`:: boot from CDROM.`-c`:: run UserConfig, the boot-time kernel configurator`-s`:: boot into single-user mode`-v`:: be more verbose during kernel startup
6353 **Note:** There are other boot flags; read [boot(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=boot§ion=8) for more information on them.
6363 CategoryHandbook-booting
6371 ## 7.5 Init: Process Control Initialization
6375 Once the kernel has finished booting, it passes control to the user process [init(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=init§ion=8), which is located at `/sbin/init`, or the program path specified in the `init_path` variable in `loader`.
6379 ### 7.5.1 Automatic Reboot Sequence
6383 The automatic reboot sequence makes sure that the file systems available on the system are consistent. If they are not, and [fsck(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=fsck§ion=8) cannot fix the inconsistencies, [init(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=init§ion=8) drops the system into [single-user mode](boot-init.html#BOOT-SINGLEUSER) for the system administrator to take care of the problems directly.
6387 ### 7.5.2 Single-User Mode
6391 This mode can be reached through the [automatic reboot sequence](boot-init.html#BOOT-AUTOREBOOT), or by the user booting with the `-s` option or setting the `boot_single` variable in `loader`.
6395 It can also be reached by calling [shutdown(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=shutdown§ion=8) without the reboot (`-r`) or halt (`-h`) options, from [multi-user mode](boot-init.html#BOOT-MULTIUSER).
6399 If the system `console` is set to `insecure` in `/etc/ttys`, then the system prompts for the `root` password before initiating single-user mode.
6403 ***'Example 7-3. An Insecure Console in `/etc/ttys`***'
6409 # name getty type status comments
6413 # If console is marked "insecure", then init will ask for the root password
6415 # when going to single-user mode.
6417 console none unknown off insecure
6423 **Note:** An `insecure` console means that you consider your physical security to the console to be insecure, and want to make sure only someone who knows the `root` password may use single-user mode, and it does not mean that you want to run your console insecurely. Thus, if you want security, choose `insecure`, not `secure`.
6427 ### 7.5.3 Multi-User Mode
6431 If [init(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=init§ion=8) finds your file systems to be in order, or once the user has finished in [single-user mode](boot-init.html#BOOT-SINGLEUSER), the system enters multi-user mode, in which it starts the resource configuration of the system.
6435 #### 7.5.3.1 Resource Configuration (rc)
6439 The resource configuration system reads in configuration defaults from `/etc/defaults/rc.conf`, and system-specific details from `/etc/rc.conf`, and then proceeds to mount the system file systems mentioned in `/etc/fstab`, start up networking services, start up miscellaneous system daemons, and finally runs the startup scripts of locally installed packages.
6443 The [rc(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rc§ion=8) manual page is a good reference to the resource configuration system, as is examining the scripts themselves.
6453 CategoryHandbook-booting
6461 ## 7.6 Shutdown Sequence
6465 Upon controlled shutdown, via [shutdown(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=shutdown§ion=8), [init(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=init§ion=8) will attempt to run the script `/etc/rc.shutdown`, and then proceed to send all processes the `TERM` signal, and subsequently the `KILL` signal to any that do not terminate timely.
6469 To power down a DragonFly machine on architectures and systems that support power management, simply use the command `shutdown -p now` to turn the power off immediately. To just reboot a DragonFly system, just use `shutdown -r now`. You need to be `root` or a member of `operator` group to run [shutdown(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=shutdown§ion=8). The [halt(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=halt§ion=8) and [reboot(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=reboot§ion=8) commands can also be used, please refer to their manual pages and to [shutdown(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=shutdown§ion=8)'s one for more information.
6473 **Note:** Power management requires [acpi(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=acpi§ion=4) support in the kernel or loaded as a module, or [apm(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=apm§ion=4) support.
6477 <!-- this section needs the info about sernos and vfs.mountrootfrom or whatever it's called -->
6483 CategoryHandbook-booting
6501 ## Chapter 8 Users and Basic Account Management
6503 ***Contributed by Neil Blakey-Milner. ***
6511 DragonFly allows multiple users to use the computer at the same time. Obviously, only one of those users can be sitting in front of the screen and keyboard at any one time [(1)](#FTN.AEN6502), but any number of users can log in through the network to get their work done. To use the system every user must have an account.
6514 After reading this chapter, you will know:
6517 * The differences between the various user accounts on a DragonFly system.
6520 * How to add user accounts.
6523 * How to remove user accounts.
6526 * How to change account details, such as the user's full name, or preferred shell.
6529 * How to set limits on a per-account basis, to control the resources such as memory and CPU time that accounts and groups of accounts are allowed to access.
6532 * How to use groups to make account management easier.
6536 Before reading this chapter, you should:
6541 * Understand the basics of UNIX® and DragonFly ([Chapter 3](basics.html)).
6550 <tablestyle="width:100%"> [ (1)](users.html#AEN6502) | Well, unless you hook up multiple terminals, but we will save that for [ Chapter 17](serialcomms.html).
6572 All access to the system is achieved via accounts, and all processes are run by users, so user and account management are of integral importance on DragonFly systems.
6576 Every account on a DragonFly system has certain information associated with it to identify the account.
6580 * User name: The user name as it would be typed at the login: prompt. User names must be unique across the computer; you may not have two users with the same user name. There are a number of rules for creating valid user names, documented in [passwd(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=passwd§ion=5); you would typically use user names that consist of eight or fewer all lower case characters.Password:: Each account has a password associated with it. The password may be blank, in which case no password will be required to access the system. This is normally a very bad idea; every account should have a password.
6582 * User ID (UID): The UID is a number, traditionally from 0 to 65535[(1)](#FTN.USERS-LARGEUIDGID), used to uniquely identify the user to the system. Internally, DragonFly uses the UID to identify users--any DragonFly commands that allow you to specify a user name will convert it to the UID before working with it. This means that you can have several accounts with different user names but the same UID. As far as DragonFly is concerned, these accounts are one user. It is unlikely you will ever need to do this.
6584 * Group ID (GID): The GID is a number, traditionally from 0 to 65535[users-introduction.html#FTN.USERS-LARGEUIDGID (1)], used to uniquely identify the primary group that the user belongs to. Groups are a mechanism for controlling access to resources based on a user's GID rather than their UID. This can significantly reduce the size of some configuration files. A user may also be in more than one group.
6586 * Login class: Login classes are an extension to the group mechanism that provide additional flexibility when tailoring the system to different users.
6588 * Password change time: By default DragonFly does not force users to change their passwords periodically. You can enforce this on a per-user basis, forcing some or all of your users to change their passwords after a certain amount of time has elapsed.
6590 * Account expiry time: By default DragonFly does not expire accounts. If you are creating accounts that you know have a limited lifespan, for example, in a school where you have accounts for the students, then you can specify when the account expires. After the expiry time has elapsed the account cannot be used to log in to the system, although the account's directories and files will remain.
6592 * User's full name: The user name uniquely identifies the account to DragonFly, but does not necessarily reflect the user's real name. This information can be associated with the account.
6594 * Home directory: The home directory is the full path to a directory on the system in which the user will start when logging on to the system. A common convention is to put all user home directories under `/home/`***username***. The user would store their personal files in their home directory, and any directories they may create in there.
6596 * User shell: The shell provides the default environment users use to interact with the system. There are many different kinds of shells, and experienced users will have their own preferences, which can be reflected in their account settings.
6600 There are three main types of accounts: the [users-superuser.html Superuser], [users-system.html system users], and [users-user.html user accounts]. The Superuser account, usually called `root`, is used to manage the system with no limitations on privileges. System users run services. Finally, user accounts are used by real people, who log on, read mail, and so forth.
6609 <tablestyle="width:100%"> [users-introduction.html#USERS-LARGEUIDGID (1)] | It is possible to use UID/GIDs as large as 4294967295, but such IDs can cause serious problems with software that makes assumptions about the values of IDs. |
6619 CategoryHandbook-usermanagement
6628 ## 8.3 The Superuser Account
6632 The superuser account, usually called `root`, comes preconfigured to facilitate system administration, and should not be used for day-to-day tasks like sending and receiving mail, general exploration of the system, or programming.
6636 This is because the superuser, unlike normal user accounts, can operate without limits, and misuse of the superuser account may result in spectacular disasters. User accounts are unable to destroy the system by mistake, so it is generally best to use normal user accounts whenever possible, unless you especially need the extra privilege.
6640 You should always double and triple-check commands you issue as the superuser, since an extra space or missing character can mean irreparable data loss.
6644 So, the first thing you should do after reading this chapter is to create an unprivileged user account for yourself for general usage if you have not already. This applies equally whether you are running a multi-user or single-user machine. Later in this chapter, we discuss how to create additional accounts, and how to change between the normal user and superuser.
6654 CategoryHandbook-usermanagement
6663 ## 8.4 System Accounts
6667 System users are those used to run services such as DNS, mail, web servers, and so forth. The reason for this is security; if all services ran as the superuser, they could act without restriction.
6671 Examples of system users are `daemon`, `operator`, `bind` (for the Domain Name Service), and `news`. Often sysadmins create `httpd` to run web servers they install.
6675 `nobody` is the generic unprivileged system user. However, it is important to keep in mind that the more services that use `nobody`, the more files and processes that user will become associated with, and hence the more privileged that user becomes.
6685 CategoryHandbook-usermanagement
6696 ## 8.5 User Accounts
6700 User accounts are the primary means of access for real people to the system, and these accounts insulate the user and the environment, preventing the users from damaging the system or other users, and allowing users to customize their environment without affecting others.
6704 Every person accessing your system should have a unique user account. This allows you to find out who is doing what, prevent people from clobbering each others' settings or reading each others' mail, and so forth.
6708 Each user can set up their own environment to accommodate their use of the system, by using alternate shells, editors, key bindings, and language.
6718 CategoryHandbook-usermanagement
6726 ## 8.6 Modifying Accounts
6730 There are a variety of different commands available in the UNIX® environment to manipulate user accounts. The most common commands are summarized below, followed by more detailed examples of their usage.
6736 [adduser(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=adduser§ion=8) | The recommended command-line application for adding new users.
6737 [rmuser(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rmuser§ion=8) | The recommended command-line application for removing users.
6738 [chpass(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=chpass§ion=1) | A flexible tool to change user database information.
6739 [passwd(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=passwd§ion=1) | The simple command-line tool to change user passwords.
6740 [pw(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=pw§ion=8) | A powerful and flexible tool to modify all aspects of user accounts. |
6748 [adduser(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=adduser§ion=8) is a simple program for adding new users. It creates entries in the system `passwd` and `group` files. It will also create a home directory for the new user, copy in the default configuration files (***dotfiles***) from `/usr/share/skel`, and can optionally mail the new user a welcome message.
6752 To create the initial configuration file, use `adduser -s -config_create`. [(1)](#FTN.AEN6699) Next, we configure [adduser(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=adduser§ion=8) defaults, and create our first user account, since using `root` for normal usage is evil and nasty.
6756 **Example 8-1. Configuring `adduser` and adding a user**
6762 Use option -silent if you don't want to see all warnings and questions.
6766 Check /etc/master.passwd
6770 Enter your default shell: csh date no sh tcsh zsh [sh]: zsh
6772 Your default shell is: zsh -> /usr/local/bin/zsh
6774 Enter your default HOME partition: [/home]:
6776 Copy dotfiles from: /usr/share/skel no [/usr/share/skel]:
6778 Send message from file: /etc/adduser.message no
6780 [/etc/adduser.message]: no
6784 Use passwords (y/n) [y]: y
6788 Write your changes to /etc/adduser.conf? (y/n) [n]: y
6794 Don't worry about mistakes. I will give you the chance later to correct any input.
6796 Enter username [a-z0-9_-]: jru
6798 Enter full name []: J. Random User
6800 Enter shell csh date no sh tcsh zsh [zsh]:
6802 Enter home directory (full path) [/home/jru]:
6806 Enter login class: default []:
6808 Login group jru [jru]:
6810 Login group is ***jru***. Invite jru into other groups: guest no
6816 Enter password again []:
6824 Fullname: J. Random User
6836 Shell: /usr/local/bin/zsh
6840 Added user ***jru***
6842 Copy files from /usr/share/skel to /home/jru
6844 Add another user? (y/n) [y]: n
6852 In summary, we changed the default shell to **zsh** (an additional shell found in pkgsrc®), and turned off the sending of a welcome mail to added users. We then saved the configuration, created an account for `jru`, and made sure `jru` is in `wheel` group (so that she may assume the role of `root` with the [su(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=su§ion=1) command.)
6855 **Note:** The password you type in is not echoed, nor are asterisks displayed. Make sure you do not mistype the password twice.
6858 **Note:** Just use [adduser(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=adduser§ion=8) without arguments from now on, and you will not have to go through changing the defaults. If the program asks you to change the defaults, exit the program, and try the `-s` option.
6866 You can use [rmuser(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rmuser§ion=8) to completely remove a user from the system. [rmuser(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rmuser§ion=8) performs the following steps:
6870 1. Removes the user's [crontab(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=crontab§ion=1) entry (if any).
6872 1. Removes any [at(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=at§ion=1) jobs belonging to the user.
6874 1. Kills all processes owned by the user.
6876 1. Removes the user from the system's local password file.
6878 1. Removes the user's home directory (if it is owned by the user).
6880 1. Removes the incoming mail files belonging to the user from `/var/mail`.
6882 1. Removes all files owned by the user from temporary file storage areas such as `/tmp`.
6884 1. Finally, removes the username from all groups to which it belongs in `/etc/group`.
6886 **Note:** If a group becomes empty and the group name is the same as the username, the group is removed; this complements the per-user unique groups created by [adduser(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=adduser§ion=8).
6890 [rmuser(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rmuser§ion=8) cannot be used to remove superuser accounts, since that is almost always an indication of massive destruction.
6894 By default, an interactive mode is used, which attempts to make sure you know what you are doing.
6898 **Example 8-2. `rmuser` Interactive Account Removal**
6906 Matching password entry:
6908 jru:*:1001:1001::0:0:J. Random User:/home/jru:/usr/local/bin/zsh
6910 Is this the entry you wish to remove? y
6912 Remove user's home directory (/home/jru)? y
6914 Updating password file, updating databases, done.
6916 Updating group file: trusted (removing group jru -- personal group is empty) done.
6918 Removing user's incoming mail file /var/mail/jru: done.
6920 Removing files belonging to jru from /tmp: done.
6922 Removing files belonging to jru from /var/tmp: done.
6924 Removing files belonging to jru from /var/tmp/vi.recover: done.
6936 [chpass(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=chpass§ion=1) changes user database information such as passwords, shells, and personal information.
6939 Only system administrators, as the superuser, may change other users' information and passwords with [chpass(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=chpass§ion=1).
6942 When passed no options, aside from an optional username, [chpass(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=chpass§ion=1) displays an editor containing user information. When the user exists from the editor, the user database is updated with the new information.
6946 ***'Example 8-3. Interactive `chpass` by Superuser***'
6952 #Changing user database information for jru.
6960 Gid [# or name]: 1001
6962 Change [month day year]:
6964 Expire [month day year]:
6968 Home directory: /home/jru
6970 Shell: /usr/local/bin/zsh
6972 Full Name: J. Random User
6986 The normal user can change only a small subset of this information, and only for themselves.
6990 **Example 8-4. Interactive chpass by Normal User**
6994 #Changing user database information for jru.
6996 Shell: /usr/local/bin/zsh
6998 Full Name: J. Random User
7012 **Note:** [chfn(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=chfn§ion=1) and [chsh(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=chsh§ion=1) are just links to [chpass(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=chpass§ion=1), as are [ypchpass(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ypchpass§ion=1), [ypchfn(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ypchfn§ion=1), and [ypchsh(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ypchsh§ion=1). NIS support is automatic, so specifying the `yp` before the command is not necessary. If this is confusing to you, do not worry, NIS will be covered in [advanced-networking.html Chapter 19].
7020 [passwd(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=passwd§ion=1) is the usual way to change your own password as a user, or another user's password as the superuser.
7024 **Note:** To prevent accidental or unauthorized changes, the original password must be entered before a new password can be set.
7028 **Example 8-5. Changing Your Password**
7036 Changing local password for jru.
7042 Retype new password:
7044 passwd: updating the database...
7052 ***'Example 8-6. Changing Another User's Password as the Superuser***'
7060 Changing local password for jru.
7064 Retype new password:
7066 passwd: updating the database...
7074 **Note:** As with [chpass(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=chpass§ion=1), [yppasswd(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=yppasswd§ion=1) is just a link to [passwd(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=passwd§ion=1), so NIS works with either command.
7082 [pw(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=pw§ion=8) is a command line utility to create, remove, modify, and display users and groups. It functions as a front end to the system user and group files. [pw(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=pw§ion=8) has a very powerful set of command line options that make it suitable for use in shell scripts, but new users may find it more complicated than the other commands presented here.
7091 <tablestyle#"width:100%"> [(1)](users-modifying.html#AEN6699) | The `-s` makes [adduser(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=adduser§ion=8) default to quiet. We use `-v` later when we want to change defaults. |
7101 CategoryHandbook-usermanagement
7109 ## 8.7 Limiting Users
7111 <!-- XXX: check this section, I got the feeling there might be something outdated in it. I'm not familiar with it -->
7113 If you have users, the ability to limit their system use may have come to mind. DragonFly provides several ways an administrator can limit the amount of system resources an individual may use. These limits are divided into two sections: disk quotas, and other resource limits.
7117 Disk quotas limit disk usage to users, and they provide a way to quickly check that usage without calculating it every time. Quotas are discussed in [quotas.html Section 12.12].
7121 The other resource limits include ways to limit the amount of CPU, memory, and other resources a user may consume. These are defined using login classes and are discussed here.
7125 Login classes are defined in `/etc/login.conf`. The precise semantics are beyond the scope of this section, but are described in detail in the [login.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=login.conf§ion=5) manual page. It is sufficient to say that each user is assigned to a login class (`default` by default), and that each login class has a set of login capabilities associated with it. A login capability is a `name=value` pair, where `name` is a well-known identifier and `value` is an arbitrary string processed accordingly depending on the name. Setting up login classes and capabilities is rather straight-forward and is also described in [login.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=login.conf§ion=5).
7129 Resource limits are different from plain vanilla login capabilities in two ways. First, for every limit, there is a soft (current) and hard limit. A soft limit may be adjusted by the user or application, but may be no higher than the hard limit. The latter may be lowered by the user, but never raised. Second, most resource limits apply per process to a specific user, not the user as a whole. Note, however, that these differences are mandated by the specific handling of the limits, not by the implementation of the login capability framework (i.e., they are not ***really*** a special case of login capabilities).
7133 And so, without further ado, below are the most commonly used resource limits (the rest, along with all the other login capabilities, may be found in [login.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=login.conf§ion=5)).
7138 * `coredumpsize`: The limit on the size of a core file generated by a program is, for obvious reasons, subordinate to other limits on disk usage (e.g., `filesize`, or disk quotas). Nevertheless, it is often used as a less-severe method of controlling disk space consumption: since users do not generate core files themselves, and often do not delete them, setting this may save them from running out of disk space should a large program (e.g., **emacs** ) crash.
7141 * `cputime`: This is the maximum amount of CPU time a user's process may consume. Offending processes will be killed by the kernel.
7143 **Note:** This is a limit on CPU ***time*** consumed, not percentage of the CPU as displayed in some fields by [top(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=top§ion=1) and [ps(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ps§ion=1). A limit on the latter is, at the time of this writing, not possible, and would be rather useless: legitimate use of a compiler, for instance, can easily use almost 100% of a CPU for some time.
7146 * `filesize`: This is the maximum size of a file the user may possess. Unlike [quotas.html disk quotas], this limit is enforced on individual files, not the set of all files a user owns.
7149 * `maxproc`: This is the maximum number of processes a user may be running. This includes foreground and background processes alike. For obvious reasons, this may not be larger than the system limit specified by the `kern.maxproc` [sysctl(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=sysctl§ion=8). Also note that setting this too small may hinder a user's productivity: it is often useful to be logged in multiple times or execute pipelines. Some tasks, such as compiling a large program, also spawn multiple processes (e.g., [make(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=make§ion=1), [cc(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=cc§ion=1), and other intermediate preprocessors).
7152 * `memorylocked`: This is the maximum amount a memory a process may have requested to be locked into main memory (e.g., see [mlock(2)](http://leaf.dragonflybsd.org/cgi/web-man?command=mlock§ion2)). Some system-critical programs, such as [amd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=amd§ion=8), lock into main memory such that in the event of being swapped out, they do not contribute to a system's trashing in time of trouble.
7155 * `memoryuse`: This is the maximum amount of memory a process may consume at any given time. It includes both core memory and swap usage. This is not a catch-all limit for restricting memory consumption, but it is a good start.
7158 * `openfiles`: This is the maximum amount of files a process may have open. In DragonFly, files are also used to represent sockets and IPC channels; thus, be careful not to set this too low. The system-wide limit for this is defined by the `kern.maxfiles` [sysctl(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=sysctl§ion=8).
7161 * `sbsize`: This is the limit on the amount of network memory, and thus mbufs, a user may consume. This originated as a response to an old DoS attack by creating a lot of sockets, but can be generally used to limit network communications.
7164 * `stacksize`: This is the maximum size a process' stack may grow to. This alone is not sufficient to limit the amount of memory a program may use; consequently, it should be used in conjunction with other limits.
7168 There are a few other things to remember when setting resource limits. Following are some general tips, suggestions, and miscellaneous comments.
7173 * Processes started at system startup by `/etc/rc` are assigned to the `daemon` login class.
7176 * Although the `/etc/login.conf` that comes with the system is a good source of reasonable values for most limits, only you, the administrator, can know what is appropriate for your system. Setting a limit too high may open your system up to abuse, while setting it too low may put a strain on productivity.
7179 * Users of the X Window System (X11) should probably be granted more resources than other users. X11 by itself takes a lot of resources, but it also encourages users to run more programs simultaneously.
7182 * Remember that many limits apply to individual processes, not the user as a whole. For example, setting `openfiles` to 50 means that each process the user runs may open up to 50 files. Thus, the gross amount of files a user may open is the value of `openfiles` multiplied by the value of `maxproc`. This also applies to memory consumption.
7186 For further information on resource limits and login classes and capabilities in general, please consult the relevant manual pages: [cap_mkdb(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#cap_mkdb§ion1), [getrlimit(2)](http://leaf.dragonflybsd.org/cgi/web-man?command=getrlimit§ion=2), [login.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=login.conf§ion=5).
7196 CategoryHandbook-usermanagement
7206 ## 8.8 Personalizing Users
7210 Localization is an environment set up by the system administrator or user to accommodate different languages, character sets, date and time standards, and so on. This is discussed in [this chapter](l10n.html).
7220 CategoryHandbook-usermanagement
7234 A group is simply a list of users. Groups are identified by their group name and GID (Group ID). In DragonFly (and most other UNIX® like systems), the two factors the kernel uses to decide whether a process is allowed to do something is its user ID and list of groups it belongs to. Unlike a user ID, a process has a list of groups associated with it. You may hear some things refer to the ***group ID*** of a user or process; most of the time, this just means the first group in the list.
7238 The group name to group ID map is in `/etc/group`. This is a plain text file with four colon-delimited fields. The first field is the group name, the second is the encrypted password, the third the group ID, and the fourth the comma-delimited list of members. It can safely be edited by hand (assuming, of course, that you do not make any syntax errors!). For a more complete description of the syntax, see the [group(5)](http://leaf.dragonflybsd.org/cgi/web-man?command#group§ion5) manual page.
7242 If you do not want to edit `/etc/group` manually, you can use the [pw(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#pw§ion8) command to add and edit groups. For example, to add a group called `teamtwo` and then confirm that it exists you can use:
7246 **Example 8-7. Adding a Group Using pw(8)**
7252 # pw groupadd teamtwo
7254 # pw groupshow teamtwo
7262 The number `1100` above is the group ID of the group `teamtwo`. Right now, `teamtwo` has no members, and is thus rather useless. Let's change that by inviting `jru` to the `teamtwo` group.
7266 **Example 8-8. Adding Somebody to a Group Using pw(8)**
7272 # pw groupmod teamtwo -M jru
7274 # pw groupshow teamtwo
7282 The argument to the `-M` option is a comma-delimited list of users who are members of the group. From the preceding sections, we know that the password file also contains a group for each user. The latter (the user) is automatically added to the group list by the system; the user will not show up as a member when using the `groupshow` command to [pw(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#pw§ion8), but will show up when the information is queried via [id(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=id§ion=1) or similar tool. In other words, [pw(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=pw§ion=8) only manipulates the `/etc/group` file; it will never attempt to read additionally data from `/etc/passwd`.
7286 **Example 8-9. Using id(1) to Determine Group Membership**
7294 uid#1001(jru) gid1001(jru) groups=1001(jru), 1100(teamtwo)
7300 As you can see, `jru` is a member of the groups `jru` and `teamtwo`.
7304 For more information about [pw(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#pw§ion8), see its manual page, and for more information on the format of `/etc/group`, consult the [group(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=group§ion=5) manual page.
7314 CategoryHandbook-usermanagement
7330 ## Configuring the DragonFly Kernel
7332 ***Updated and restructured by Jim Mock. Originally contributed by Jake Hamby.***
7338 The kernel is the core of the DragonFly operating system. It is responsible for managing memory, enforcing security controls, networking, disk access, and much more. While more and more of DragonFly becomes dynamically configurable it is still occasionally necessary to reconfigure and recompile your kernel.
7340 After reading this chapter, you will know:
7342 * Why you might need to build a custom kernel.
7343 * How to write a kernel configuration file, or alter an existing configuration file.
7344 * How to use the kernel configuration file to create and build a new kernel.
7345 * How to install the new kernel.
7346 * How to troubleshoot if things go wrong.
7351 ## Why Build a Custom Kernel?
7355 Traditionally, DragonFly has had what is called a ***monolithic*** kernel. This means that the kernel was one large program, supported a fixed list of devices, and if you wanted to change the kernel's behavior then you had to compile a new kernel, and then reboot your computer with the new kernel.
7357 Today, DragonFly is rapidly moving to a model where much of the kernel's functionality is contained in modules which can be dynamically loaded and unloaded from the kernel as necessary. This allows the kernel to adapt to new hardware suddenly becoming available (such as PCMCIA cards in a laptop), or for new functionality to be brought into the kernel that was not necessary when the kernel was originally compiled. This is known as a modular kernel. Colloquially these are called KLDs.
7359 Despite this, it is still necessary to carry out some static kernel configuration. In some cases this is because the functionality is so tied to the kernel that it can not be made dynamically loadable. In others it may simply be because no one has yet taken the time to write a dynamic loadable kernel module for that functionality yet.
7361 Building a custom kernel is one of the most important rites of passage nearly every UNIX® user must endure. This process, while time consuming, will provide many benefits to your DragonFly system. Unlike the `GENERIC` kernel, which must support a wide range of hardware, a custom kernel only contains support for ***your*** PC's hardware. This has a number of benefits, such as:
7365 * Faster boot time. Since the kernel will only probe the hardware you have on your system, the time it takes your system to boot will decrease dramatically.
7367 * Less memory usage. A custom kernel often uses less memory than the `GENERIC` kernel, which is important because the kernel must always be present in real memory. For this reason, a custom kernel is especially useful on a system with a small amount of RAM.
7369 * Additional hardware support. A custom kernel allows you to add in support for devices such as sound cards, which are not present in the `GENERIC` kernel.
7377 ## Building and Installing a Custom Kernel
7379 First, let us take a quick tour of the kernel build directory. All directories mentioned will be relative to the main `/usr/src/sys` directory, which is also accessible through `/sys`. There are a number of subdirectories here representing different parts of the kernel, but the most important, for our purposes, is `config`, where you will edit your custom kernel configuration, and `compile`, which is the staging area where your kernel will be built. Notice the logical organization of the directory structure, with each supported device, file system, and option in its own subdirectory.
7381 ### Installing the Source
7383 If there is ***not*** a `/usr/src/sys` directory on your system, then the kernel source has not been installed. One method to do this is via git. An alternative is to install the kernel source tree from the archive distributed on the DragonFly CD named `src-sys.tar.bz2`. This is especially useful when you do not have ready access to the internet. Use the Makefile in `/usr` to fetch the source or to unpack the archive. When installing kernel source only, use the alternate build procedure below.
7385 The preferred way of installing the sources is:
7390 This will download the whole source tree via git into /usr/src. This method also allows for easy updating of the source tree by using:
7396 ### Your Custom Config File
7398 Next, move to the `config` directory and copy the `GENERIC` configuration file to the name you want to give your kernel. For example:
7400 # cd /usr/src/sys/config
7401 # cp GENERIC MYKERNEL
7403 Traditionally, this name is in all capital letters and, if you are maintaining multiple DragonFly machines with different hardware, it is a good idea to name it after your machine's hostname. We will call it `MYKERNEL` for the purpose of this example.
7405 **Tip:** Storing your kernel config file directly under `/usr/src` can be a bad idea. If you are experiencing problems it can be tempting to just delete `/usr/src` and start again. Five seconds after you do that you realize that you have deleted your custom kernel config file. Do not edit `GENERIC` directly, as it may get overwritten the next time you [update your source tree](updating.html#UPDATING-SETUP), and your kernel modifications will be lost. You might want to keep your kernel config file elsewhere, and then create a symbolic link to the file in the `config` directory.
7412 # cd /usr/src/sys/config
7413 # mkdir /root/kernels
7414 # cp GENERIC /root/kernels/MYKERNEL
7415 # ln -s /root/kernels/MYKERNEL
7418 **Note:** You must execute these and all of the following commands under the `root` account or you will get permission denied errors.
7420 Now, edit `MYKERNEL` with your favorite text editor. If you are just starting out, the only editor available will probably be ***vi***, which is too complex to explain here, but is covered well in many books in the [bibliography](bibliography.html). However, DragonFly does offer an easier editor called ***ee*** which, if you are a beginner, should be your editor of choice. Feel free to change the comment lines at the top to reflect your configuration or the changes you have made to differentiate it from `GENERIC`.
7422 If you have built a kernel under SunOS™ or some other BSD operating system, much of this file will be very familiar to you. If you are coming from some other operating system such as DOS, on the other hand, the `GENERIC` configuration file might seem overwhelming to you, so follow the descriptions in the [[Configuration File|handbook-kernelconfig-config]] section slowly and carefully.
7426 ### Building a Kernel - Full Source Tree
7428 **Note:** Be sure to always check the file `/usr/src/UPDATING`, before you perform any update steps, in the case you [sync your source tree](updating.html#UPDATING-SETUP) with the latest sources of the DragonFly project. In this file all important issues with updating DragonFly are typed out. `/usr/src/UPDATING` always fits your version of the DragonFly source, and is therefore more accurate for new information than the handbook.
7432 1. Change to the `/usr/src` directory.
7438 1. Compile the kernel.
7440 # make buildkernel KERNCONF=MYKERNEL
7443 1. Install the new kernel.
7445 # make installkernel KERNCONF=MYKERNEL
7451 If you have ***not*** upgraded your source tree in any way since the last time you successfully completed a `buildworld`-`installworld` cycle (you have not run `git pull` ), then it is safe to use the `quickworld` and `quickkernel`, `buildworld`, `buildkernel` sequence.
7453 ### Building a Kernel - Kernel Source Only
7455 When only the kernel source is installed, you need to change step 2, above, to this:
7458 # make nativekernel KERNCONF=MYKERNEL
7461 The other steps are the same.
7465 ### Running Your New Kernel
7467 The new kernel will have been copied to the boot directory as `kernel` and the old kernel will be moved to `/boot/kernel.old`, the same applies to the modules (`/boot/modules` -> `/boot/modules.old`). Now, shutdown the system and reboot to use your new kernel. In case something goes wrong, there are some [troubleshooting](kernelconfig-trouble.html) instructions at the end of this chapter. Be sure to read the section which explains how to recover in case your new kernel [does not boot](kernelconfig-trouble.html#KERNELCONFIG-NOBOOT).
7470 **Note:** If you have added any new devices (such as sound cards), you may have to add some device nodes to your `/dev` directory before you can use them. For more information, take a look at device nodes section later on in this chapter.
7475 ## The Configuration File
7476 <!-- XXX: do we really want to mention all these million config options? -->
7477 The general format of a configuration file is quite simple. Each line contains a keyword and one or more arguments. For simplicity, most lines only contain one argument. Anything following a `#` is considered a comment and ignored. The following sections describe each keyword, generally in the order they are listed in `GENERIC`, although some related keywords have been grouped together in a single section (such as Networking) even though they are actually scattered throughout the `GENERIC` file. An exhaustive list of options and more detailed explanations of the device lines is present in the `LINT` configuration file, located in the same directory as `GENERIC`. If you are in doubt as to the purpose or necessity of a line, check first in `LINT`.
7481 The following is an example `GENERIC` kernel configuration file with various additional comments where needed for clarity. This example should match your copy in `/usr/src/sys/config/GENERIC` fairly closely. For details of all the possible kernel options, see `/usr/src/sys/config/LINT`.
7491 # GENERIC -- Generic kernel configuration file for DragonFly/i386
7495 # Check the LINT configuration file in sys/config, for an
7497 # exhaustive list of options.
7501 # $DragonFly: src/sys/config/GENERIC,v 1.56 2007/12/26 14:02:36 sephe Exp $
7505 The following are the mandatory keywords required in ***every*** kernel you build:
7515 This is the machine architecture. It must be `i386` at the moment. Support for `amd64` will be added in the future.
7531 The above option specifies the type of CPU you have in your system. You may have multiple instances of the CPU line (i.e., you are not sure whether you should use `I586_CPU` or `I686_CPU`), however, for a custom kernel, it is best to specify only the CPU you have. If you are unsure of your CPU type, you can check the `/var/run/dmesg.boot` file to view your boot up messages.
7541 This is the identification of the kernel. You should change this to whatever you named your kernel, i.e. `MYKERNEL` if you have followed the instructions of the previous examples. The value you put in the `ident` string will print when you boot up the kernel, so it is useful to give the new kernel a different name if you want to keep it separate from your usual kernel (i.e. you want to build an experimental kernel).
7551 The `maxusers` option sets the size of a number of important system tables. This number is supposed to be roughly equal to the number of simultaneous users you expect to have on your machine.
7555 (Recommended) The system will auto-tune this setting for you if you explicitly set it to `0`[(1)](#FTN.AEN7414). If you want to manage it yourself you will want to set `maxusers` to at least 4, especially if you are using the X Window System or compiling software. The reason is that the most important table set by `maxusers` is the maximum number of processes, which is set to `20 + 16 * maxusers`, so if you set `maxusers` to 1, then you can only have 36 simultaneous processes, including the 18 or so that the system starts up at boot time, and the 15 or so you will probably create when you start the X Window System. Even a simple task like reading a manual page will start up nine processes to filter, decompress, and view it. Setting `maxusers` to 64 will allow you to have up to 1044 simultaneous processes, which should be enough for nearly all uses. If, however, you see the dreaded proc table full error when trying to start another program, or are running a server with a large number of simultaneous users, you can always increase the number and rebuild.
7559 **Note:** `maxusers` does ***not*** limit the number of users which can log into your machine. It simply sets various table sizes to reasonable values considering the maximum number of users you will likely have on your system and how many processes each of them will be running. One keyword which ***does*** limit the number of simultaneous ***remote logins and X terminal windows*** is [kernelconfig-config.html#KERNELCONFIG-PTYS `pseudo-device pty 16`].
7565 # Floating point support - do not disable.
7567 device npx0 at nexus? port IO_NPX irq 13
7571 `npx0` is the interface to the floating point math unit in DragonFly, which is either the hardware co-processor or the software math emulator. This is ***not*** optional.
7577 # Pseudo devices - the number indicates how many units to allocate.
7579 pseudo-device loop # Network loopback
7583 This is the generic loopback device for TCP/IP. If you telnet or FTP to `localhost` (a.k.a., `127.0.0.1`) it will come back at you through this device. This is ***mandatory***.
7587 Everything that follows is more or less optional. See the notes underneath or next to each option for more information.
7593 #makeoptions DEBUG=-g #Build kernel with gdb(1) debug symbols
7597 The normal build process of the DragonFly does not include debugging information when building the kernel and strips most symbols after the resulting kernel is linked, to save some space at the install location. If you are going to do tests of kernels in the DEVELOPMENT branch or develop changes of your own for the DragonFly kernel, you might want to uncomment this line. It will enable the use of the `-g` option which enables debugging information when passed to [gcc(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#gcc§ion1).
7603 options MATH_EMULATE #Support for x87 emulation
7607 This line allows the kernel to simulate a math co-processor if your computer does not have one (386 or 486SX). If you have a 486DX, or a 386 or 486SX (with a separate 387 or 487 chip), or higher (Pentium®, Pentium II, etc.), you can comment this line out.
7611 **Note:** The normal math co-processor emulation routines that come with DragonFly are ***not*** very accurate. If you do not have a math co-processor, and you need the best accuracy, it is recommended that you change this option to `GPL_MATH_EMULATE` to use the GNU math support, which is not included by default for licensing reasons.
7617 options INET #InterNETworking
7621 Networking support. Leave this in, even if you do not plan to be connected to a network. Most programs require at least loopback networking (i.e., making network connections within your PC), so this is essentially mandatory.
7627 options INET6 #IPv6 communications protocols
7631 This enables the IPv6 communication protocols.
7637 options FFS #Berkeley Fast Filesystem
7639 options FFS_ROOT #FFS usable as root device [keep this!]
7643 This is the basic hard drive Filesystem. Leave it in if you boot from the hard disk.
7649 options UFS_DIRHASH #Improve performance on big directories
7653 This option includes functionality to speed up disk operations on large directories, at the expense of using additional memory. You would normally keep this for a large server, or interactive workstation, and remove it if you are using DragonFly on a smaller system where memory is at a premium and disk access speed is less important, such as a firewall.
7659 options SOFTUPDATES #Enable FFS Soft Updates support
7663 This option enables Soft Updates in the kernel, this will help speed up write access on the disks. Even when this functionality is provided by the kernel, it must be turned on for specific disks. Review the output from [mount(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#mount§ion8) to see if Soft Updates is enabled for your system disks. If you do not see the `soft-updates` option then you will need to activate it using the [tunefs(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=tunefs§ion=8) (for existing filesystems) or [newfs(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=newfs§ion=8) (for new filesystems) commands.
7669 options MFS #Memory Filesystem
7671 options MD_ROOT #MD is a potential root device
7675 This is the memory-mapped filesystem. This is basically a RAM disk for fast storage of temporary files, useful if you have a lot of swap space that you want to take advantage of. A perfect place to mount an MFS partition is on the `/tmp` directory, since many programs store temporary data here. To mount an MFS RAM disk on `/tmp`, add the following line to `/etc/fstab`:
7681 /dev/ad1s2b /tmp mfs rw 0 0
7685 Now you simply need to either reboot, or run the command `mount /tmp`.
7691 options NFS #Network Filesystem
7693 options NFS_ROOT #NFS usable as root device, NFS required
7697 The network Filesystem. Unless you plan to mount partitions from a UNIX® file server over TCP/IP, you can comment these out.
7703 options MSDOSFS #MSDOS Filesystem
7707 The MS-DOS® Filesystem. Unless you plan to mount a DOS formatted hard drive partition at boot time, you can safely comment this out. It will be automatically loaded the first time you mount a DOS partition, as described above. Also, the excellent ***mtools*** software (in pkgsrc®) allows you to access DOS floppies without having to mount and unmount them (and does not require `MSDOSFS` at all).
7713 options CD9660 #ISO 9660 Filesystem
7715 options CD9660_ROOT #CD-ROM usable as root, CD9660 required
7719 The ISO 9660 Filesystem for CDROMs. Comment it out if you do not have a CDROM drive or only mount data CDs occasionally (since it will be dynamically loaded the first time you mount a data CD). Audio CDs do not need this Filesystem.
7725 options PROCFS #Process filesystem
7729 The process filesystem. This is a ***pretend*** filesystem mounted on `/proc` which allows programs like [ps(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ps§ion1) to give you more information on what processes are running. ***
7737 Compatibility with 4.3BSD. Leave this in; some programs will act strangely if you comment this out.
7743 options SCSI_DELAY=5000 #Delay (in ms) before probing SCSI
7747 This causes the kernel to pause for 15 seconds before probing each SCSI device in your system. If you only have IDE hard drives, you can ignore this, otherwise you will probably want to lower this number, perhaps to five seconds (5000 ms), to speed up booting. Of course, if you do this, and DragonFly has trouble recognizing your SCSI devices, you will have to raise it back up.
7753 options UCONSOLE #Allow users to grab the console
7757 Allow users to grab the console, which is useful for X users. For example, you can create a console ***xterm*** by typing `xterm -C`, which will display any [write(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#write§ion1), [talk(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=talk§ion=1), and any other messages you receive, as well as any console messages sent by the kernel.
7763 options USERCONFIG #boot -c editor
7767 This option allows you to boot the configuration editor from the boot menu.
7773 options VISUAL_USERCONFIG #visual boot -c editor
7777 This option allows you to boot the visual configuration editor from the boot menu.
7783 options KTRACE #ktrace(1) support
7787 This enables kernel process tracing, which is useful in debugging.
7793 options SYSVSHM #SYSV-style shared memory
7797 This option provides for System V shared memory. The most common use of this is the XSHM extension in X, which many graphics-intensive programs will automatically take advantage of for extra speed. If you use X, you will definitely want to include this.
7803 options SYSVSEM #SYSV-style semaphores
7807 Support for System V semaphores. Less commonly used but only adds a few hundred bytes to the kernel.
7813 options SYSVMSG #SYSV-style message queues
7817 Support for System V messages. Again, only adds a few hundred bytes to the kernel.
7821 **Note:** The [ipcs(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ipcs§ion1) command will list any processes using each of these System V facilities.
7827 options P1003_1B #Posix P1003_1B real-time extensions
7829 options _KPOSIX_PRIORITY_SCHEDULING
7833 Real-time extensions added in the 1993 POSIX®. Certain applications in the ports collection use these (such as **StarOffice™** ).
7839 options ICMP_BANDLIM #Rate limit bad replies
7843 This option enables ICMP error response bandwidth limiting. You typically want this option as it will help protect the machine from denial of service packet attacks.
7849 # To make an SMP kernel, the next two are needed
7851 #options SMP # Symmetric MultiProcessor Kernel
7853 #options APIC_IO # Symmetric (APIC) I/O
7857 The above are both required for SMP support.
7867 All PCs supported by DragonFly have one of these. Do not remove, even if you have no ISA slots. If you have an IBM PS/2 (Micro Channel Architecture), DragonFly provides some limited support at this time. For more information about the MCA support, see `/usr/src/sys/config/LINT`.
7877 Include this if you have an EISA motherboard. This enables auto-detection and configuration support for all devices on the EISA bus.
7887 Include this if you have a PCI motherboard. This enables auto-detection of PCI cards and gatewaying from the PCI to ISA bus.
7897 Include this if you have an AGP card in the system. This will enable support for AGP, and AGP GART for boards which have these features.
7905 device fdc0 at isa? port IO_FD1 irq 6 drq 2
7907 device fd0 at fdc0 drive 0
7909 device fd1 at fdc0 drive 1
7913 This is the floppy drive controller. `fd0` is the `A:` floppy drive, and `fd1` is the `B:` drive.
7923 This driver supports all ATA and ATAPI devices. You only need one `device ata` line for the kernel to detect all PCI ATA/ATAPI devices on modern machines.
7929 device atadisk # ATA disk drives
7933 This is needed along with `device ata` for ATA disk drives.
7939 device atapicd # ATAPI CDROM drives
7943 This is needed along with `device ata` for ATAPI CDROM drives.
7949 device atapifd # ATAPI floppy drives
7953 This is needed along with `device ata` for ATAPI floppy drives.
7959 device atapist # ATAPI tape drives
7963 This is needed along with `device ata` for ATAPI tape drives.
7969 options ATA_STATIC_ID #Static device numbering
7973 This makes the controller number static (like the old driver) or else the device numbers are dynamically allocated.
7979 # ATA and ATAPI devices
7981 device ata0 at isa? port IO_WD1 irq 14
7983 device ata1 at isa? port IO_WD2 irq 15
7987 Use the above for older, non-PCI systems.
7995 device ahb # EISA AHA1742 family
7997 device ahc # AHA2940 and onboard AIC7xxx devices
7999 device amd # AMD 53C974 (Teckram DC-390(T))
8001 device dpt # DPT Smartcache - See LINT for options!
8003 device isp # Qlogic family
8005 device ncr # NCR/Symbios Logic
8007 device sym # NCR/Symbios Logic (newer chipsets)
8021 SCSI controllers. Comment out any you do not have in your system. If you have an IDE only system, you can remove these altogether.
8029 device scbus # SCSI bus (required)
8031 device da # Direct Access (disks)
8033 device sa # Sequential Access (tape etc)
8037 device pass # Passthrough device (direct SCSI
8043 SCSI peripherals. Again, comment out any you do not have, or if you have only IDE hardware, you can remove them completely.
8047 **Note:** The USB [umass(4)](http://leaf.dragonflybsd.org/cgi/web-man?command#umass§ion4) driver (and a few other drivers) use the SCSI subsystem even though they are not real SCSI devices. Therefore make sure not to remove SCSI support, if any such drivers are included in the kernel configuration.
8055 device ida # Compaq Smart RAID
8057 device amr # AMI MegaRAID
8059 device mlx # Mylex DAC960 family
8063 Supported RAID controllers. If you do not have any of these, you can comment them out or remove them.
8069 # atkbdc0 controls both the keyboard and the PS/2 mouse
8071 device atkbdc0 at isa? port IO_KBD
8075 The keyboard controller (`atkbdc`) provides I/O services for the AT keyboard and PS/2 style pointing devices. This controller is required by the keyboard driver (`atkbd`) and the PS/2 pointing device driver (`psm`).
8081 device atkbd0 at atkbdc? irq 1
8085 The `atkbd` driver, together with `atkbdc` controller, provides access to the AT 84 keyboard or the AT enhanced keyboard which is connected to the AT keyboard controller.
8091 device psm0 at atkbdc? irq 12
8095 Use this device if your mouse plugs into the PS/2 mouse port.
8105 The video card driver.
8111 # splash screen/screen saver
8113 pseudo-device splash
8117 Splash screen at start up! Screen savers require this too.
8123 # syscons is the default console driver, resembling an SCO console
8129 `sc0` is the default console driver, which resembles a SCO console. Since most full-screen programs access the console through a terminal database library like `termcap`, it should not matter whether you use this or `vt0`, the `VT220` compatible console driver. When you log in, set your `TERM` variable to `scoansi` if full-screen programs have trouble running under this console.
8135 # Enable this and PCVT_FREEBSD for pcvt vt220 compatible console driver
8139 #options XSERVER # support for X server on a vt console
8141 #options FAT_CURSOR # start with block cursor
8143 # If you have a ThinkPAD, uncomment this along with the rest of the PCVT lines
8145 #options PCVT_SCANSET=2 # IBM keyboards are non-std
8149 This is a VT220-compatible console driver, backward compatible to VT100/102. It works well on some laptops which have hardware incompatibilities with `sc0`. Also set your `TERM` variable to `vt100` or `vt220` when you log in. This driver might also prove useful when connecting to a large number of different machines over the network, where `termcap` or `terminfo` entries for the `sc0` device are often not available -- `vt100` should be available on virtually any platform.
8155 # Power management support (see LINT for more options)
8157 device apm0 at nexus? disable flags 0x20 # Advanced Power Management
8161 Advanced Power Management support. Useful for laptops.
8167 # PCCARD (PCMCIA) support
8171 device pcic0 at isa? irq 10 port 0x3e0 iomem 0xd0000
8173 device pcic1 at isa? irq 11 port 0x3e2 iomem 0xd4000 disable
8177 PCMCIA support. You want this if you are using a laptop.
8183 # Serial (COM) ports
8185 device sio0 at isa? port IO_COM1 flags 0x10 irq 4
8187 device sio1 at isa? port IO_COM2 irq 3
8189 device sio2 at isa? disable port IO_COM3 irq 5
8191 device sio3 at isa? disable port IO_COM4 irq 9
8195 These are the four serial ports referred to as COM1 through COM4 in the MS-DOS/Windows® world.
8199 **Note:** If you have an internal modem on COM4 and a serial port at COM2, you will have to change the IRQ of the modem to 2 (for obscure technical reasons, IRQ2 # IRQ 9) in order to access it from DragonFly. If you have a multiport serial card, check the manual page for [sio(4)](http://leaf.dragonflybsd.org/cgi/web-man?commandsio§ion=4) for more information on the proper values for these lines. Some video cards (notably those based on S3 chips) use IO addresses in the form of `0x*2e8`, and since many cheap serial cards do not fully decode the 16-bit IO address space, they clash with these cards making the COM4 port practically unavailable.
8203 Each serial port is required to have a unique IRQ (unless you are using one of the multiport cards where shared interrupts are supported), so the default IRQs for COM3 and COM4 cannot be used.
8211 device ppc0 at isa? irq 7
8215 This is the ISA-bus parallel port interface.
8221 device ppbus # Parallel port bus (required)
8225 Provides support for the parallel port bus.
8231 device lpt # Printer
8235 Support for parallel port printers.
8239 **Note:** All three of the above are required to enable parallel printer support.
8245 device plip # TCP/IP over parallel
8249 This is the driver for the parallel network interface.
8255 device ppi # Parallel port interface device
8259 The general-purpose I/O (***geek port) + IEEE1284 I/O.
8265 #device vpo # Requires scbus and da
8269 This is for an Iomega Zip drive. It requires `scbus` and `da` support. Best performance is achieved with ports in EPP 1.9 mode.
8275 # PCI Ethernet NICs.
8277 device de # DEC/Intel DC21x4x (Tulip)
8279 device fxp # Intel EtherExpress PRO/100B (82557, 82558)
8281 device tx # SMC 9432TX (83c170 EPIC)
8283 device vx # 3Com 3c590, 3c595 (Vortex)
8285 device wx # Intel Gigabit Ethernet Card (Wiseman)
8289 Various PCI network card drivers. Comment out or remove any of these not present in your system.
8295 # PCI Ethernet NICs that use the common MII bus controller code.
8297 device miibus # MII bus support
8301 MII bus support is required for some PCI 10/100 Ethernet NICs, namely those which use MII-compliant transceivers or implement transceiver control interfaces that operate like an MII. Adding `device miibus` to the kernel config pulls in support for the generic miibus API and all of the PHY drivers, including a generic one for PHYs that are not specifically handled by an individual driver.
8307 device dc # DEC/Intel 21143 and various workalikes
8309 device rl # RealTek 8129/8139
8311 device sf # Adaptec AIC-6915 (Starfire)
8313 device sis # Silicon Integrated Systems SiS 900/SiS 7016
8315 device ste # Sundance ST201 (D-Link DFE-550TX)
8317 device tl # Texas Instruments ThunderLAN
8319 device vr # VIA Rhine, Rhine II
8321 device wb # Winbond W89C840F
8323 device xl # 3Com 3c90x (Boomerang, Cyclone)
8327 Drivers that use the MII bus controller code.
8333 # ISA Ethernet NICs.
8335 device ed0 at isa? port 0x280 irq 10 iomem 0xd8000
8341 # WaveLAN/IEEE 802.11 wireless NICs. Note: the WaveLAN/IEEE really
8343 # exists only as a PCMCIA device, so there is no ISA attachment needed
8345 # and resources will always be dynamically assigned by the pccard code.
8349 # Aironet 4500/4800 802.11 wireless NICs. Note: the declaration below will
8351 # work for PCMCIA and PCI cards, as well as ISA cards set to ISA PnP
8353 # mode (the factory default). If you set the switches on your ISA
8355 # card for a manually chosen I/O address and IRQ, you must specify
8357 # those parameters here.
8361 # The probe order of these is presently determined by i386/isa/isa_compat.c.
8363 device ie0 at isa? port 0x300 irq 10 iomem 0xd0000
8365 device fe0 at isa? port 0x300
8367 device le0 at isa? port 0x300 irq 5 iomem 0xd0000
8369 device lnc0 at isa? port 0x280 irq 10 drq 0
8371 device cs0 at isa? port 0x300
8373 device sn0 at isa? port 0x300 irq 10
8375 # requires PCCARD (PCMCIA) support to be activated
8381 ISA Ethernet drivers. See `/usr/src/sys/config/LINT` for which cards are supported by which driver.
8387 pseudo-device ether # Ethernet support
8391 `ether` is only needed if you have an Ethernet card. It includes generic Ethernet protocol code.
8397 pseudo-device sl 1 # Kernel SLIP
8401 `sl` is for SLIP support. This has been almost entirely supplanted by PPP, which is easier to set up, better suited for modem-to-modem connection, and more powerful. The ***number*** after `sl` specifies how many simultaneous SLIP sessions to support.
8407 pseudo-device ppp 1 # Kernel PPP
8411 This is for kernel PPP support for dial-up connections. There is also a version of PPP implemented as a userland application that uses `tun` and offers more flexibility and features such as demand dialing. The ***number*** after `ppp` specifies how many simultaneous PPP connections to support. .
8417 device tun # Packet tunnel.
8421 This is used by the userland PPP software. A ***number*** after `tun` specifies the number of simultaneous PPP sessions to support. See the [userppp.html PPP] section of this book for more information.
8427 pseudo-device pty # Pseudo-ttys (telnet etc)
8431 This is a ***pseudo-terminal*** or simulated login port. It is used by incoming `telnet` and `rlogin` sessions, ***xterm***, and some other applications such as ***Emacs***. The ***number*** after `pty` indicates the number of `pty`s to create. If you need more than the default of 16 simultaneous ***xterm*** windows and/or remote logins, be sure to increase this number accordingly, up to a maximum of 256. ***
8439 Memory disk pseudo-devices.
8445 pseudo-device gif # IPv6 and IPv4 tunneling
8449 This implements IPv6 over IPv4 tunneling, IPv4 over IPv6 tunneling, IPv4 over IPv4 tunneling, and IPv6 over IPv6 tunneling.
8455 pseudo-device faith # IPv6-to-IPv4 relaying (translation)
8459 This pseudo-device captures packets that are sent to it and diverts them to the IPv4/IPv6 translation daemon.
8465 # The `bpf' device enables the Berkeley Packet Filter.
8467 # Be aware of the administrative consequences of enabling this!
8469 pseudo-device bpf # Berkeley packet filter
8473 This is the Berkeley Packet Filter. This pseudo-device allows network interfaces to be placed in promiscuous mode, capturing every packet on a broadcast network (e.g., an Ethernet). These packets can be captured to disk and or examined with the [tcpdump(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#tcpdump§ion1) program.
8477 **Note:** The [bpf(4)](http://leaf.dragonflybsd.org/cgi/web-man?command#bpf§ion4) device is also used by [dhclient(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=dhclient§ion=8) to obtain the IP address of the default router (gateway) and so on. If you use DHCP, leave this uncommented.
8485 #device uhci # UHCI PCI->USB interface
8487 #device ohci # OHCI PCI->USB interface
8489 #device usb # USB Bus (required)
8491 #device ugen # Generic
8493 #device uhid # ***Human Interface Devices***
8495 #device ukbd # Keyboard
8497 #device ulpt # Printer
8499 #device umass # Disks/Mass storage - Requires scbus and da
8503 # USB Ethernet, requires mii
8505 #device aue # ADMtek USB ethernet
8507 #device cue # CATC USB ethernet
8509 #device kue # Kawasaki LSI USB ethernet
8513 Support for various USB devices.
8517 For more information and additional devices supported by DragonFly, see `/usr/src/sys/i386/conf/LINT`.
8524 <tablewidth="100%"> [(1)](kernelconfig-config.html#AEN7414) | The auto-tuning algorithm sets `maxuser` equal to the amount of memory in the system, with a minimum of 32, and a maximum of 384. |
8537 Almost every device in the kernel has a corresponding node entry in the `/dev` directory. These nodes look like regular files, but are actually special entries into the kernel which programs use to access the device.
8539 These nodes are created automatically once devfs is mounted, which happens manually for the root `/dev` during boot, just after the root mount.
8543 ## If Something Goes Wrong
8546 **Note:** If you are having trouble building a kernel, make sure to keep a `GENERIC`, or some other kernel that is known to work on hand as a different name that will not get erased on the next build. You cannot rely on `kernel.old` because when installing a new kernel, `kernel.old` is overwritten with the last installed kernel which may be non-functional. Also, as soon as possible, move the working kernel to the proper `kernel` location or commands such as [ps(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ps§ion1) will not work properly. The proper command to ***unlock*** the kernel file that `make` installs (in order to move another kernel back permanently) is:
8549 % chflags noschg /boot/kernel
8552 If you find you cannot do this, you are probably running at a [securelevel(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#securelevel§ion8) greater than zero. Edit `kern_securelevel` in `/etc/rc.conf` and set it to `-1`, then reboot. You can change it back to its previous setting when you are happy with your new kernel.
8554 And, if you want to ***lock*** your new kernel into place, or any file for that matter, so that it cannot be moved or tampered with:
8558 % chflags schg /boot/kernel
8562 There are five categories of trouble that can occur when building a custom kernel. They are:
8567 * `config` fails: If the [config(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#config§ion8) command fails when you give it your kernel description, you have probably made a simple error somewhere. Fortunately, [config(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=config§ion=8) will print the line number that it had trouble with, so you can quickly skip to it with ***vi***. For example, if you see `config: line 17: syntax error`. You can skip to the problem in ***vi*** by typing `17G` in command mode. Make sure the keyword is typed correctly, by comparing it to the `GENERIC` kernel or another reference.
8572 * `make` fails: If the `make` command fails, it usually signals an error in your kernel description, but not severe enough for [config(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#config§ion8) to catch it. Again, look over your configuration, and if you still cannot resolve the problem, send mail to the [DragonFly Bugs mailing list](http://leaf.dragonflybsd.org/mailarchive/) with your kernel configuration, and it should be diagnosed very quickly.
8577 * Installing the new kernel fails: If the kernel compiled fine, but failed to install (the `make install` or `make installkernel` command failed), the first thing to check is if your system is running at securelevel 1 or higher (see [init(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#init§ion8)). The kernel installation tries to remove the immutable flag from your kernel and set the immutable flag on the new one. Since securelevel 1 or higher prevents unsetting the immutable flag for any files on the system, the kernel installation needs to be performed at securelevel 0 or lower.
8582 * The kernel does not boot: If your new kernel does not boot, or fails to recognize your devices, do not panic! Fortunately, DragonFly has an excellent mechanism for recovering from incompatible kernels. Simply choose the kernel you want to boot from at the DragonFly boot loader. You can access this when the system counts down from 10. Hit any key except for the **Enter** key, type `unload` and then type `boot ***kernel.old***`, or the filename of any other kernel that will boot properly. When reconfiguring a kernel, it is always a good idea to keep a kernel that is known to work on hand. After booting with a good kernel you can check over your configuration file and try to build it again. One helpful resource is the `/var/log/messages` file which records, among other things, all of the kernel messages from every successful boot. Also, the [dmesg(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#dmesg§ion8) command will print the kernel messages from the current boot.
8586 * The kernel works, but [ps(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ps§ion1) does not work any more: If you have installed a different version of the kernel from the one that the system utilities have been built with, many system-status commands like [ps(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ps§ion=1) and [vmstat(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=vmstat§ion=8) will not work any more. You must recompile the `libkvm` library as well as these utilities. This is one reason it is not normally a good idea to use a different version of the kernel from the rest of the operating system.
projects / ikiwiki.git / blob