1 # Chapter 1 Introduction
3 ***Restructured, reorganized, and parts rewritten by Jim Mock. ***
7 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.
9 After reading this chapter, you will know:
11 * How DragonFly relates to other computer operating systems.
13 * The history of the DragonFly Project.
15 * The goals of the DragonFly Project.
17 * The basics of the DragonFly open-source development model.
19 * And of course: where the name ***DragonFly*** comes from.
23 ## Welcome to DragonFly!
25 DragonFly is a [[4.4BSD-Lite|http://en.wikipedia.org/wiki/Berkeley_Software_Distribution]] unix operating system for Intel (x86) and amd64 (x86_64) architectures.
27 ### What Can DragonFly Do?
29 <!-- Cutout of "features". This is outdated bullshit -->
31 Work on BSD-flavor Unix systems running on PC compatible hardware started as a fork of the 4.4BSD-Lite release from Computer Systems Research Group (CSRG) at the University of California at Berkeley. One of the variants that became quite popular became known later as FreeBSD. Firefly BSD started out as a fork, and continuation of FreeBSD 4.8.
33 Like all other modern PC compatible BSD variants, it carries on the distinguished tradition of BSD systems development. In addition to the fine work provided by CSRG, the DragonFly Project has put in many thousands of hours in fine tuning the system for maximum performance and reliability in real-life load situations.
35 As many of the commercial giants struggle to field PC operating systems with such features, performance and reliability, DragonFly can offer them ***now***!
36 For example the `Hammer` filesystem, which is the default filesystem in DragonFly BSD, is the most powerful and reliable filesystem available on any operating system.
38 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.
40 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:
42 The robust TCP/IP networking built into DragonFly makes it an ideal platform for a variety of Internet services such as:
45 * World Wide Web servers (standard or secure [SSL])
46 * Firewalls and NAT (***IP masquerading***) gateways
47 * Electronic Mail servers
48 * USENET News or Bulletin Board Systems
51 With DragonFly, you can install on almost any PC, from older 32 bit computers running 386 or Pentium chips, to modern 64 bit Intel Core or AMD X64 desktop CPUs, and even up to and including high end Xeon CPUs. All of these CPUs share a common ancestry, and instruction set, going back to the original Intel 80386 CPU which was the first fully 32-bit desktop CPU for "IBM PC compatible" computers.
53 Here are some of the fields where people are using Dragonfly BSD, and the reasons that they find DragonFly BSD fits their needs:
55 * ***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!
57 * ***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.
59 * ***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.
61 * ***X Window workstation:*** DragonFly is a fine choice for an inexpensive X terminal solution, using the freely available X.org server. Unlike an X terminal, DragonFly allows many applications to be run locally if desired, thus relieving the burden on a central server. DragonFly can even boot ***diskless***, making individual workstations even cheaper and easier to administer.
63 * ***Software Development:*** The basic DragonFly system comes with a full complement of development tools including the renowned GNU C/C++ compiler and debugger.
65 DragonFly is available via anonymous FTP or GIT. Please see [Appendix A](mirrors.html) for more information about obtaining DragonFly.
67 For more help on installing, see the appropriate sections of this handbook.
71 ## About the DragonFly Project
73 The following section provides some background information on the project, including a brief history, project goals, and the development model of the project.
75 ### A Brief History of DragonFly
77 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.
79 ### DragonFly Project Goals
81 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.
83 ### The DragonFly Development Model
85 ***Written by Justin Sherrill. ***
87 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.
89 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.
91 ### The Current DragonFly Release
93 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.
97 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.
99 ## Updating the System
101 ### Supported methods
103 The only **supported** method of upgrading DragonFly BSD is by building from source code. <br><br>
104 Supported upgrade process includes going from the *previous release* to *latest release*.<br>
106 For example, in our actual case, only the upgrade process involving <u>2.10.x up to 3.0.x</u> would be supported.
108 ### Getting the source code
110 There is a Makefile in /usr which will ease the task of retrieving the source tree; it needs to be run as root:
116 And that will effectively checkout the source tree on `/usr/src` and switch to master branch. For stable branch you need to check it out with the following command (remember to replace the *DragonFly_RELEASE_3_0* with the appropriate branch name for the release needed).
119 % git checkout DragonFly_RELEASE_3_0
121 To see the available remote branches:
127 The leading edge (development trunk) version of the system will be the "master".
129 ### Build and upgrade process
131 Build process requires some time to build all the userland programs and the DragonFly BSD kernel. Once built, next step is to install everything and make the upgrade target. No configuration files in */etc* are changed by this process. More details can be found in **[build(7)](http://leaf.dragonflybsd.org/cgi/web-man?command=build§ion=ANY)** manpage.
141 **Note:** You may use a concurrent build if you have a SMP (a machine with several cores or CPUs). You may specify *-j x* parameter to make where x is the number of CPUs + 1. <br>
142 If you run DragonFly 2.12 or higher the kernel will auto-detect the number of CPUs your computer has and activate them all if possible. To find out how many CPUs your computer has:
148 An explanation of each step follows.
150 * <u>*make buildworld*</u> : This command builds all userland programs and it is the most time-consuming step.<br>
151 Some programs may be discarded from the build process.<br>
152 For more details check **[make.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=make.conf§ion=ANY)** manpage.
154 * <u>*make buildkernel*</u> : This builds the kernel using the config file by default for your architecture. You may also specify a different kernel configuration file using KERNCONF=configfile. More details on **[make.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=make.conf§ion=ANY)** manpage.
156 * <u>*make installkernel*</u> This installs the kernel using the config file for your architecture or KERNCONF=file can be used to specify which one to install.
158 * <u>*make installworld*</u> : This copies all the files built in the buildworld step (i.e. everything that is not the kernel) to the proper places in the filesystem.
160 * <u>*make upgrade*</u> : This cleans out any files made unnecessary by this upgrade.
162 * (reboot) : Reboot the computer to load the new kernel and use the new files installed as part of this process.
164 If your computer fails to boot the new kernel, you can always select 'Boot DragonFly using kernel.old' in the loader menu, so that the old kernel is loaded instead of the new one.
166 Additional upgrading instructions can be found in */usr/src/UPDATING* in the source tree. Online it can be found **[here](http://gitweb.dragonflybsd.org/dragonfly.git/blob_plain/master:/UPDATING)**
168 # DragonFly BSD Quick Start
170 This QuickStart is part of the [[NewHandbook|/docs/newhandbook/]].
172 This document describes the DragonFly environment one will find on a newly installed system. While you are getting started please pay careful attention to the version or level of DragonFly that the documentation was written for. Some documentation on this site may be out of date. Watch for the marker `(obsolete)` on items that are out of date or need updating.
175 ## Some Unix and BSD Fundamentals
177 If you have used another Unix flavor, another BSD or Linux before, you may need to spend some time learning basic subjects. If you have never used any flavor of Unix, BSD or otherwise, and have only used Windows before, please be prepared for a lengthy period of learning.
179 If you already know your way around a Unix filesystem, and already know what the `/etc` folder is, how to use `vi` or `vim` to edit a file, how to use a shell like `tcsh` or `bash`, how to configure that shell, or change what shell you're using, how `su` and `sudo` work, and what a `root` account is, then you may get a lot farther in using any BSD variant (like Dragonfly BSD) then the rest of this page may be enough to orient you to your surroundings.
181 You should understand everything in the [[Unix Basics|/docs/newhandbook/UnixBasics/]] section before you proceed with trying to use your new system.
183 ## Disk layout of a New Dragonfly BSD System using the HAMMER filesystem
185 If you chose to install on the HAMMER file system during installation you will be left with a system with the following disk configuration:
188 Filesystem Size Used Avail Capacity Mounted on
189 ROOT 288G 12G 276G 4% /
190 devfs 1.0K 1.0K 0B 100% /dev
191 /dev/serno/9VMBWDM1.s1a 756M 138M 558M 20% /boot
192 /pfs/@@-1:00001 288G 12G 276G 4% /var
193 /pfs/@@-1:00002 288G 12G 276G 4% /tmp
194 /pfs/@@-1:00003 288G 12G 276G 4% /usr
195 /pfs/@@-1:00004 288G 12G 276G 4% /home
196 /pfs/@@-1:00005 288G 12G 276G 4% /usr/obj
197 /pfs/@@-1:00006 288G 12G 276G 4% /var/crash
198 /pfs/@@-1:00007 288G 12G 276G 4% /var/tmp
199 procfs 4.0K 4.0K 0B 100% /proc
203 * `/dev/serno/9VMBWDM1` is the hard disk specified with serial number,
204 * `/dev/serno/9VMBWDM1.s1` is the first slice on the hard disk.
206 The disklabel looks at follows
208 # disklabel /dev/serno/9VMBWDM1.s1
210 # /dev/serno/9VMBWDM1.s1:
212 # Informational fields calculated from the above
213 # All byte equivalent offsets must be aligned
215 # boot space: 1044992 bytes
216 # data space: 312567643 blocks # 305241.84 MB (320069266944 bytes)
218 # NOTE: If the partition data base looks odd it may be
219 # physically aligned instead of slice-aligned
221 diskid: e67030af-d2af-11df-b588-01138fad54f5
223 boot2 data base: 0x000000001000
224 partitions data base: 0x000000100200
225 partitions data stop: 0x004a85ad7000
226 backup label: 0x004a85ad7000
227 total size: 0x004a85ad8200 # 305242.84 MB
229 display block size: 1024 # for partition display only
232 # size offset fstype fsuuid
233 a: 786432 0 4.2BSD # 768.000MB
234 b: 8388608 786432 swap # 8192.000MB
235 d: 303392600 9175040 HAMMER # 296281.836MB
236 a-stor_uuid: eb1c8aac-d2af-11df-b588-01138fad54f5
237 b-stor_uuid: eb1c8aec-d2af-11df-b588-01138fad54f5
238 d-stor_uuid: eb1c8b21-d2af-11df-b588-01138fad54f5
240 The slice has 3 partitions:
244 * `d` - for `/`, a HAMMER file system labeled ROOT
246 When you create a HAMMER file system you must give it a label, here the installer labeled it as "ROOT" and mounted it as
248 ROOT 288G 12G 276G 4% /
250 A PFS is a Pseudo File System inside a HAMMER file system. The HAMMER file system in which the PFSes are created is referred to as the root file system. You should not confuse the "root" file system with the Label "ROOT", the label can be anything. It is just that the installer labeled it as ROOT because it is mounted as `/`.
252 Now inside the ROOT HAMMER file system you find the installed created 7 PFSes from the `df -h` output above, let us see how they are mounted in `/etc/fstab`:
256 # Device Mountpoint FStype Options Dump Pass#
257 /dev/serno/9VMBWDM1.s1a /boot ufs rw 1 1
258 /dev/serno/9VMBWDM1.s1b none swap sw 0 0
259 /dev/serno/9VMBWDM1.s1d / hammer rw 1 1
260 /pfs/var /var null rw 0 0
261 /pfs/tmp /tmp null rw 0 0
262 /pfs/usr /usr null rw 0 0
263 /pfs/home /home null rw 0 0
264 /pfs/usr.obj /usr/obj null rw 0 0
265 /pfs/var.crash /var/crash null rw 0 0
266 /pfs/var.tmp /var/tmp null rw 0 0
267 proc /proc procfs rw 0 0
269 The PFSes are mounted using a NULL mount because they are also HAMMER file systems. You can read more on NULL mounts here [mount_null(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=mount_null§ion=8).
271 You don't need to specify a size for the PFSes like you do for logical volumes inside a volume group for LVM. All the free space in the root HAMMER file system is available to all the PFSs. That is the reason in the `df -h` output above you saw free space is same for all PFSes and the root HAMMER file system.
273 Now if you look in `/var`
277 account backups caps cron empty log msgs run spool yp at
278 cache crash db games lib mail preserve rwho tmp
280 you will find the above directories.
282 If you look at the status of one of the PFSes, e.g. `/usr` you will see `/var/hammer` is the default snapshot directory.
284 # hammer pfs-status /usr/
286 sync-beg-tid=0x0000000000000001
287 sync-end-tid=0x0000000117ac6270
288 shared-uuid=f33e318e-d2af-11df-b588-01138fad54f5
289 unique-uuid=f33e31cb-d2af-11df-b588-01138fad54f5
292 operating as a MASTER
293 snapshots directory defaults to /var/hammer/<pfs>
296 There is no "hammer" directory in `/var` now. That is because no snapshots are yet taken. You can verify this by checking the snapshots available for `/usr`
299 Snapshots on /usr PFS #3
300 Transaction ID Timestamp Note
302 Snapshots will appear automatically each night as the system performs housekeeping on the Hammer filesystem. For a new volume, an immediate snapshot can be taken by running the command 'hammer cleanup'. Among other activites, it will take a snapshot of the filesystem.
304 # sudo hammer cleanup
305 cleanup / - HAMMER UPGRADE: Creating snapshots
306 Creating snapshots in /var/hammer/root
307 handle PFS #0 using /var/hammer/root
313 cleanup /var - HAMMER UPGRADE: Creating snapshots
315 cleanup /tmp - HAMMER UPGRADE: Creating snapshots
317 cleanup /usr - HAMMER UPGRADE: Creating snapshots
319 cleanup /home - HAMMER UPGRADE: Creating snapshots
321 cleanup /usr/obj - HAMMER UPGRADE: Creating snapshots
323 cleanup /var/crash - HAMMER UPGRADE: Creating snapshots
325 cleanup /var/tmp - HAMMER UPGRADE: Creating snapshots
327 cleanup /var/isos - HAMMER UPGRADE: Creating snapshots
330 No snapshots were taken for `/tmp`, `/usr/obj` and `/var/tmp`. This is because the PFSes are flagged as `nohistory`. HAMMER tracks history for all files in a PFS, naturally this consumes disk space until the history is pruned. To prevent that temporary files on the mentioned PFSes (e.g., object files, crash dumps) consume disk space, the PFSes are marked as `nohistory`.
332 In `/var` will be a new directory called *hammer* with the following sub directories
337 drwxr-xr-x 1 root wheel 0 Oct 13 11:51 home
338 drwxr-xr-x 1 root wheel 0 Oct 13 11:42 root
339 drwxr-xr-x 1 root wheel 0 Oct 13 11:43 tmp
340 drwxr-xr-x 1 root wheel 0 Oct 13 11:51 usr
341 drwxr-xr-x 1 root wheel 0 Oct 13 11:54 var
343 Well let us look inside `/var/hammer/usr`
348 drwxr-xr-x 1 root wheel 0 Oct 13 11:54 obj
349 lrwxr-xr-x 1 root wheel 25 Oct 13 11:43 snap-20101013-1143 -> /usr/@@0x0000000117ac6cb0
351 We have a symlink pointing to the snapshot transaction ID shown below.
354 Snapshots on /usr PFS #3
355 Transaction ID Timestamp Note
356 0x0000000117ac6cb0 2010-10-13 11:43:04 IST -
359 You can read more about snapshots, prune, reblance, reblock, recopy etc from [hammer(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=hammer§ion=8) especially look under the heading "cleanup [filesystem ...]"
361 You can learn more about PFS mirroring [here](http://www.dragonflybsd.org/docs/how_to_implement_hammer_pseudo_file_system__40___pfs___41___slave_mirroring_from_pfs_master/)
363 In order to correctly map hard disk sernos to device names you can use the 'devattr' command.
366 # devattr -d "ad*" -p serno
384 Or if your disks are 'da', just change it as appropiate.
386 ## Configuring and Starting the SSH Server
388 Described in detail [[here|/docs/newhandbook/sshserver/]]
390 ## Software/Programs and Configuration Files Location
392 DragonFly default installation contains the base software/programs from the DragonFly project itself and few other software from other sources.
394 The base system binary software programs are located in the folders
399 The configuration files for the base system can be found in `/etc`. There is also `/usr/local/etc` which is used by third-party programs.
401 There are several different ways to install software and which version you use depends on which DragonFly BSD version you have. You can compile things from source code, or you can use binary packages.
403 ## Installing Third-party Software
405 Have a look at the [[dports howto|/docs/howtos/HowToDPorts/]] for an in-depth description about dealing with packaging systems. Note that DragonFly BSD has several older package managers (like `pkgin`), but that the most modern binary package installation system as of 2014, is `pkg`.
409 Read [[dports howto|/docs/howtos/HowToDPorts/]] then for some errata, read [[this|http://lists.dragonflybsd.org/pipermail/users/2013-November/090339.html]].
411 You can look at the help and the man page for the pkg tool like this:
415 Example: Read man page for pkg-install
419 ### Installing an X.org desktop X11 environment and XFCE desktop
421 If it's already on your system run X by typing `startx`. If it's not, be sure to check your dports configuration is finished, then install it using `pkg install xorg-7.7 xfce4-desktop`. This will install the core X.org X11 server, and an XFCE based desktop environment.
424 Slightly out of date instructions on installing a GUI (X desktop) environment are in the [new handbook](http://www.dragonflybsd.org/docs/newhandbook/X/).
428 ***Rewritten by Chris Shumway. ***
433 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.
435 After reading this chapter, you will know:
437 * How to use the ***virtual consoles*** of DragonFly.
439 * How UNIX file permissions work along with understanding file flags in DragonFly.
441 * The default DragonFly file system layout.
443 * The DragonFly disk organization.
445 * How to mount and unmount file systems.
447 * What processes, daemons, and signals are.
449 * What a shell is, and how to change your default login environment.
451 * How to use basic text editors.
453 * What devices and device nodes are.
455 * What binary format is used under DragonFly.
457 * How to read manual pages for more information.
459 ## Virtual Consoles and Terminals
461 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.
463 <!-- XXX: also mention vesa.ko and other modes for the vt, but maybe somewhere else -->
467 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:
469 Additional ABI support:.
471 Local package initialization:.
472 Additional TCP options:.
474 Wed Feb 18 17:53:48 GMT 2009
476 DragonFly/i386 (Amnesiac) (ttyv0)
480 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:
482 DragonFly/i386 (Amnesiac) (ttyv0)
484 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:
488 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.
490 ### Logging into DragonFly
492 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.
494 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:
498 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>:
504 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.
506 ### Multiple Consoles
508 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.
510 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.
512 ### The /etc/ttys File
514 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.
516 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`:
519 # name getty type status comments
521 ttyv0 "/usr/libexec/getty Pc" cons25 on secure
523 ttyv1 "/usr/libexec/getty Pc" cons25 on secure
524 ttyv2 "/usr/libexec/getty Pc" cons25 on secure
525 ttyv3 "/usr/libexec/getty Pc" cons25 on secure
526 ttyv4 "/usr/libexec/getty Pc" cons25 on secure
527 ttyv5 "/usr/libexec/getty Pc" cons25 on secure
528 ttyv6 "/usr/libexec/getty Pc" cons25 on secure
529 ttyv7 "/usr/libexec/getty Pc" cons25 on secure
530 ttyv8 "/usr/pkg/xorg/bin/xdm -nodaemon" xterm off secure
532 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.
534 ### Single User Mode Console
536 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`:
540 # name getty type status comments
542 # If console is marked "insecure", then init will ask for the root password
543 # when going to single-user mode.
544 console none unknown off secure
546 **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.
551 <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.
552 [ (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.
553 [ (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. |
559 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.
561 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:
564 |<tablestyle="width:100%"> Value | Permission | Directory Listing
565 <tablestyle="width:100%"> 0 | No read, no write, no execute | `---`
566 1 | No read, no write, execute | `--x`
567 2 | No read, write, no execute | `-w-`
568 3 | No read, write, execute | `-wx`
569 4 | Read, no write, no execute | `r--`
570 5 | Read, no write, execute | `r-x`
571 6 | Read, write, no execute | `rw-`
572 7 | Read, write, execute | `rwx` |
576 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:
580 -rw-r--r-- 1 root wheel 512 Sep 5 12:31 myfile
581 -rw-r--r-- 1 root wheel 512 Sep 5 12:31 otherfile
582 -rw-r--r-- 1 root wheel 7680 Sep 5 12:31 email.txt
585 Here is how the first column of `ls -l` is broken up:
589 <!-- XXX: Check all these http:// links to see if they are broken -->
591 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.
593 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.
595 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).
597 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.
599 ### Symbolic Permissions
601 ***Contributed by Tom Rhodes.***
603 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:
606 <tablestyle="width:100%"> Option | Letter | Represents
607 <tablestyle="width:100%"> (who) | u | User
608 (who) | g | Group owner
610 (who) | a | All (***world***)
611 (action) | + | Adding permissions
612 (action) | - | Removing permissions
613 (action) | = | Explicitly set permissions
614 (permissions) | r | Read
615 (permissions) | w | Write
616 (permissions) | x | Execute
617 (permissions) | t | Sticky bit
618 (permissions) | s | Set UID or GID |
622 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`:
628 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:
632 % chmod go-w,a+x FILE
634 ### DragonFly File Flags
636 ***Contributed by Tom Rhodes.***
638 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:
642 # chflags sunlink file1
644 And to disable the system undeletable flag, simply issue the previous command with ***no*** in front of the `sunlink`. Observe:
648 # chflags nosunlink file1
650 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:
656 The output should look like the following:
660 -rw-r--r-- 1 trhodes trhodes sunlnk 0 Mar 1 05:54 file1
662 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.
664 ## Directory Structure
666 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.
668 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).
670 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.
673 <tablestyle="width:100%">Directory | Description
674 <tablestyle="width:100%"> `/` | Root directory of the file system.
675 `/bin/` | User utilities fundamental to both single-user and multi-user environments.
676 `/boot/` | Programs and configuration files used during operating system bootstrap.
677 `/boot/defaults/` | Default bootstrapping configuration files; see [loader.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=loader.conf§ion5).
678 `/dev/` | Device nodes; see [intro(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=intro§ion4).
679 `/etc/` | System configuration files and scripts.
680 `/etc/defaults/` | Default system configuration files; see [rc(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rc§ion8).
681 `/etc/mail/` | Configuration files for mail transport agents such as [sendmail(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=sendmail§ion8).
682 `/etc/namedb/` | `named` configuration files; see [named(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=named§ion8).
683 `/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).
684 `/etc/ppp/` | `ppp` configuration files; see [ppp(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=ppp§ion8).
685 `/mnt/` | Empty directory commonly used by system administrators as a temporary mount point.
686 `/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).
687 `/root/` | Home directory for the `root` account.
688 `/sbin/` | System programs and administration utilities fundamental to both single-user and multi-user environments.
689 `/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).
690 `/usr/` | The majority of user utilities and applications.
691 `/usr/bin/` | Common utilities, programming tools, and applications.
692 `/usr/include/` | Standard C include files.
693 `/usr/lib/` | Archive libraries.
694 `/usr/libdata/` | Miscellaneous utility data files.
695 `/usr/libexec/` | System daemons & system utilities (executed by other programs).
696 `/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`.
697 `/usr/obj/` | Architecture-specific target tree produced by building the `/usr/src` tree.
698 `/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`.
699 `/usr/pkg/xorg/` | Xorg distribution executables, libraries, etc (optional).
700 `/usr/pkgsrc` | The pkgsrc tree for installing packages (optional).
701 `/usr/sbin/` | System daemons & system utilities (executed by users).
702 `/usr/share/` | Architecture-independent files.
703 `/usr/src/` | BSD and/or local source files.
704 `/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).
705 `/var/log/` | Miscellaneous system log files.
706 `/var/mail/` | User mailbox files.
707 `/var/spool/` | Miscellaneous printer and mail system spooling directories.
708 `/var/tmp/` | Temporary files. The files are usually preserved across a system reboot, unless `/var` is a memory-based file system.
709 `/var/yp` | NIS maps. |
715 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.
717 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.
719 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`.
721 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.
723 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 `\`.
725 DragonFly does not use drive letters, or other drive names in the path. You would not write `c:/foo/bar/readme.txt` on DragonFly.
727 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.
729 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`).
731 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:
735 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:
739 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.
741 If `B` had been mounted on `A2` then the diagram would look like this:
745 and the paths would be `/A2/B1` and `/A2/B2` respectively.
747 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:
751 Or `C` could be mounted directly on to the `A` file system, under the `A1` directory:
755 If you are familiar with MS-DOS, this is similar, although not identical, to the `join` command.
757 ## Choosing File System Layout
759 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.
761 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.
763 **Benefits of Multiple File Systems**
765 * 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.
767 * 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.
769 * 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.
771 **Benefit of a Single File System**
773 * 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.
774 <!-- XXX: what about hammer? -->
776 ## Disk Slices, Partitions and local UNIX file systems
778 Here we describe how disks are subdivided.
780 <!-- XXX: mention serno stuff -->
784 A disk can be subdivided in slices.
786 Slices are named `s0`, `s1` and so on.
788 For example the disk `ad6` can contain the slice `ad6s3`.
790 DragonFly support two schemes for slices, MBR and GPT, either of them will manage all slices on a disk:
792 * 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.
794 * 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).
798 Partitions are contained in slices.
800 Partitions are named `a`, `b` and so on.
802 DragonFly support 16 partitions per slice, that is `a` through `p`.
804 For example the partition `ad6s3a` is contained in the slice `ad6s3`.
806 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):
808 * [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.
810 * [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.
812 ### Local UNIX file systems
814 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.
816 DragonFly support two local UNIX file systems, UFS and HAMMER:
818 * 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.
820 * [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.
822 ### Typical disk layout
824 From the above we see the following typical disk layout scenarios:
826 * 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.
828 * 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.
830 * 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).
834 [HAMMER(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=HAMMER&section5)
836 is a rather new file system, under active development.
838 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 .
840 All major features except the mirroring are quite well tested as-of the 2.2.1 release.
842 You should evaluate if HAMMER is suitable for your needs.
843 <!-- XXX: mention disk and memory requirements for efficient hammer use -->
845 Examples of ongoing development includes:
847 * 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).
849 * Multi master mirroring. For now only one mirror master is supported, but multiple mirror targets, called slaves, are already supported.
851 * Support for shrinking existing HAMMER file systems. The HAMMER design is prepared for this, utility just have to be written to support it.
852 <!-- XXX: is this still accurate? Do we really want to mention it here? -->
856 [HAMMER(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=HAMMER&section5) has several advanced features not found in UFS:
858 * Large file systems: Up to 1 million TB, also called 1 Exabyte is supported.
860 * 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.
862 * 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.
864 * 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.
866 * 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).
868 * 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.
870 * 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.
872 More info on HAMMER can be found [here](http://www.dragonflybsd.org/hammer/index.html).
874 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.
876 <!-- XXX: mention swapcache, and also how to configure and use it (somewhere else, probably) -->
880 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.
882 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
883 [disklabel64(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel64&section8).
885 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).
887 <!-- XXX: mention that disklabel64 is default now -->
906 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.
910 # disklabel64 -rw ad6s1 auto
912 # disklabel64 -e ad6s1 # edit label to add partitions as needed
915 <!-- XXX: what is all this fuzz about dangerously dedicated? -->
917 For [disklabel(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel&section8) labels some partitions have certain conventions associated with them.
920 <tablestyle="width:100%"> Partition | Convention
921 <tablestyle="width:100%"> `a` | Normally contains the root file system
922 `b` | Normally contains swap space
923 `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.
924 `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`. |
928 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.
930 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.
932 <!-- XXX: gpt allows for way more than 4 partitions... let's remove this stuff above -->
934 ***Dangerously dedicated*** physical drives are accessed as slice 0.
936 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.
938 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).
940 <!-- XXX: here would probably be the right place to talk about serno -->
942 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).
944 <!-- XXX: later talk also about devfs, definitely not here though. also, devfs rules -->
946 [Example 3-2](disk-organization.html#BASICS-CONCEPT-DISK-MODEL) shows a conceptual model of the disk layout that should help make things clearer.
948 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.
950 ***'Table 3-1. Disk Device Codes***'
953 <tablestyle="width:100%"> Code | Meaning
954 <tablestyle="width:100%"> `ad` | ATAPI (IDE) disk
955 `da` | SCSI direct access disk
956 `acd` | ATAPI (IDE) CDROM
963 ***'Example 3-1. Sample Disk, Slice, and Partition Names***'
966 <tablestyle="width:100%"> Name | Meaning
967 <tablestyle="width:100%"> `ad0s1a` | The first partition (`a`) on the first slice (`s1`) on the first IDE disk (`ad0`).
968 `da1s2e` | The fifth partition (`e`) on the second slice (`s2`) on the second SCSI disk (`da1`). |
972 ***'Example 3-2. Conceptual Model of a Disk***'
974 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.
976 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.
980 ## Mounting and Unmounting File Systems
982 The file system is best visualized as a tree, rooted at `/`.
984 The directories, e.g. `/dev` and `/usr`, in the root directory are branches,
986 which may have their own branches, such as `/usr/local`, and so on.
988 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.
990 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.
994 During the [boot process](boot.html), file systems listed in `/etc/fstab` are automatically mounted (unless they are listed with the `noauto` option).
996 The `/etc/fstab` file contains a list of lines of the following format:
999 device mount-point fstype options dumpfreq passno
1001 These parameters have the following meaning:
1003 * `device`: A device name (which should exist), as explained [here](disks-naming.html).
1005 * `mount-point`: A directory (which should exist), on which to mount the file system.
1007 * `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`.
1009 * `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.
1011 * `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.
1013 * `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.
1015 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.
1017 ### The mount Command
1019 The [mount(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=mount§ion8) command is what is ultimately used to mount file systems.
1021 In its most basic form, you use:
1025 # mount device mountpoint
1027 Or, if `mountpoint` is specified in `/etc/fstab`, just:
1033 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:
1037 * `-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.
1039 * `-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.
1041 * `-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.
1043 * `-r`: Mount the file system read-only. This is identical to using the `rdonly` argument to the `-o` option.
1045 * `-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.
1047 * `-u`: Update mount options on the file system.
1051 * `-w`: Mount the file system read-write.
1053 The `-o` option takes a comma-separated list of the options, including the following:
1055 * `nodev:` Do not interpret special devices on the file system. This is a useful security option.
1057 * `noexec`: Do not allow execution of binaries on this file system. This is also a useful security option.
1059 * `nosuid`: Do not interpret setuid or setgid flags on the file system. This is also a useful security option.
1061 ### The umount Command
1063 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.
1065 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.
1067 `-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.
1071 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.
1073 <!-- XXX: talk about LWPs and threads? -->
1075 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.
1077 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.
1079 By default, `ps` only shows you the commands that are running and are owned by you. For example:
1085 PID TT STAT TIME COMMAND
1086 298 p0 Ss 0:01.10 tcsh
1087 7078 p0 S 2:40.88 xemacs mdoc.xsl (xemacs-21.1.14)
1088 37393 p0 I 0:03.11 xemacs freebsd.dsl (xemacs-21.1.14)
1089 48630 p0 S 2:50.89 /usr/local/lib/netscape-linux/navigator-linux-4.77.bi
1090 48730 p0 IW 0:00.00 (dns helper) (navigator-linux-)
1091 72210 p0 R+ 0:00.00 ps
1092 390 p1 Is 0:01.14 tcsh
1093 7059 p2 Is+ 1:36.18 /usr/local/bin/mutt -y
1094 6688 p3 IWs 0:00.00 tcsh
1095 10735 p4 IWs 0:00.00 tcsh
1096 20256 p5 IWs 0:00.00 tcsh
1097 262 v0 IWs 0:00.00 -tcsh (tcsh)
1098 270 v0 IW+ 0:00.00 /bin/sh /usr/X11R6/bin/startx -- -bpp 16
1099 280 v0 IW+ 0:00.00 xinit /home/nik/.xinitrc -- -bpp 16
1100 284 v0 IW 0:00.00 /bin/sh /home/nik/.xinitrc
1101 285 v0 S 0:38.45 /usr/X11R6/bin/sawfish
1103 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.
1105 [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.
1107 The output from [top(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=top§ion1) is similar. A sample session looks like this:
1112 last pid: 72257; load averages: 0.13, 0.09, 0.03 up 0+13:38:33 22:39:10
1113 47 processes: 1 running, 46 sleeping
1114 CPU states: 12.6% user, 0.0% nice, 7.8% system, 0.0% interrupt, 79.7% idle
1115 Mem: 36M Active, 5256K Inact, 13M Wired, 6312K Cache, 15M Buf, 408K Free
1116 Swap: 256M Total, 38M Used, 217M Free, 15% Inuse
1119 PID USERNAME PRI NICE SIZE RES STATE TIME WCPU CPU COMMAND
1120 72257 nik 28 0 1960K 1044K RUN 0:00 14.86% 1.42% top
1121 7078 nik 2 0 15280K 10960K select 2:54 0.88% 0.88% xemacs-21.1.14
1122 281 nik 2 0 18636K 7112K select 5:36 0.73% 0.73% XF86_SVGA
1123 296 nik 2 0 3240K 1644K select 0:12 0.05% 0.05% xterm
1124 48630 nik 2 0 29816K 9148K select 3:18 0.00% 0.00% navigator-linu
1125 175 root 2 0 924K 252K select 1:41 0.00% 0.00% syslogd
1126 7059 nik 2 0 7260K 4644K poll 1:38 0.00% 0.00% mutt
1129 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.
1131 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.
1133 [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.
1135 ## Daemons, Signals, and Killing Processes
1137 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.
1139 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.
1141 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.
1143 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.
1145 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.
1147 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.
1149 `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).
1151 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.
1153 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.
1155 Signals are sent using the [kill(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=kill§ion=1) command, as this example shows.
1157 **Sending a Signal to a Process**
1159 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`.
1161 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).
1165 % ps -ax | grep inetd
1167 198 ?? IWs 0:00.00 inetd -wW
1171 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.
1173 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.
1181 # /bin/kill -s HUP 198
1185 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`.
1187 **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.
1189 Sending other signals is very similar, just substitute `TERM` or `KILL` in the command line as necessary.
1191 **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** .
1200 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`.
1202 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.
1204 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** ]`.
1206 The shell would print out `rm foo[BEEP].bar`.
1208 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.
1210 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:
1213 <tablestyle="width:100%"> Variable | Description
1214 <tablestyle="width:100%"> `USER` | Current logged in user's name.
1215 `PATH` | Colon separated list of directories to search for binaries.
1216 `DISPLAY` | Network name of the X11 display to connect to, if available.
1217 `SHELL` | The current shell.
1218 `TERM` | The name of the user's terminal. Used to determine the capabilities of the terminal.
1219 `TERMCAP` | Database entry of the terminal escape codes to perform various terminal functions.
1220 `OSTYPE` | Type of operating system. e.g., DragonFly.
1221 `MACHTYPE` | The CPU architecture that the system is running on.
1222 `EDITOR` | The user's preferred text editor.
1223 `PAGER` | The user's preferred text pager.
1224 `MANPATH` | Colon separated list of directories to search for manual pages. |
1228 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`:
1231 % setenv EDITOR /usr/pkg/bin/emacs
1233 Under Bourne shells:
1236 % export EDITOR="/usr/pkg/bin/emacs"
1238 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`.
1240 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.
1242 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.
1244 ### Changing Your Shell
1246 <!-- XXX: does chsh still exist? chpass will do, too -->
1248 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.
1250 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:
1254 % chsh -s /usr/pkg/bin/bash
1256 **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.
1258 For example, if you installed `bash` by hand and placed it into `/usr/local/bin`, you would want to:
1262 # echo "/usr/local/bin/bash" >> /etc/shells
1268 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.
1270 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.
1272 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.
1274 ## Devices and Device Nodes
1276 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`.
1278 For example, `acd0` is the first IDE CDROM drive, while `kbd0` represents the keyboard.
1280 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.
1282 The device nodes in the `/dev` directory are created and destroyed automatically on DragonFly >= 2.4, by means of the device file system (devfs).
1286 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®:
1288 * [a.out(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=a.out&section=5)
1290 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.
1294 The SVR3 object format. The header now comprises a section table, so you can have more than just .text, .data, and .bss sections.
1296 * [elf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=elf&section=5)
1298 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.
1300 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.
1302 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.
1304 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.
1306 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.
1308 <!-- XXX: do we really need all this bullshit about file formats? -->
1310 ## For More Information
1314 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:
1318 `command` is the name of the command you wish to learn about. For example, to learn more about `ls` command type:
1322 The online manual is divided up into numbered sections:
1325 1. System calls and error numbers.
1326 1. Functions in the C libraries.
1329 1. Games and other diversions.
1330 1. Miscellaneous information.
1331 1. System maintenance and operation commands.
1332 1. Kernel internals.
1334 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:
1339 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.
1341 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:
1347 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.
1349 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:
1360 which does the same thing.
1364 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:
1368 For a brief introduction, type `h`. For a quick command reference, type `?`.
1372 Dports is DragonFly's own third-party software build system. It is based on FreeBSD's Ports Collection. Differences between ports and DPorts are intentionally kept to a minimum, both to maintain familiarity for mutual users of both operating systems and also to leverage the tremendous amount of work the FreeBSD contributors put into ports. DPorts can and does feature ports unique to DragonFly, so it's truly a native system.
1374 The __pkgng__ tool called "pkg" is a modern and fast binary package manager. It was developed for FreeBSD, but PC-BSD used it in production first, followed soon after by DragonFly. In the future, it will be the only binary package manager on FreeBSD just as it is for DPorts.
1376 __pkgng__ is not a replacement for port management tools like `ports-mgmt/portmaster` or `ports-mgmt/portupgrade`. While `ports-mgmt/portmaster` and `ports-mgmt/portupgrade` can install third-party software from both binary packages and DPorts, __pkgng__ installs only binary packages.
1378 ## Getting started with pkgng
1380 DragonFly daily snapshots and Releases (starting with 3.4) come with __pkgng__ already installed. However upgrades from earlier releases won't have it. If the "pkg" program is missing on the system for any reason, it can be quickly bootstrapped without having to build it from source.
1382 To ensure __pkgng__ on a DragonFly BSD 3.4 or higher system is ready for use, run the following BEFORE you try to use `pkg` the first time:
1385 # make dports-create
1390 Since you may need to manually edit the configuration file `/usr/local/etc/pkg.conf` here is the
1391 usual command to edit it using the vi editor:
1393 # vi /usr/local/etc/pkg.conf
1395 Before using consult the man page (`man pkg`) and then try things like these examples:
1397 # pkg search editors
1400 To bootstrap __pkgng__ with a download on a very old version of DragonFly that is still using `pkgsrc` run:
1402 # make pkg-bootstrap
1404 # pkg-static install -y pkg
1407 Note that this step is unnecessary for any newly installed release from DragonFly 3.4 onwards.
1409 ## Configuring pkgng
1411 Information previously contained in here worked for older versions of pkg, but as pkgng has undergone some changes, so too do the configurations.
1413 Previously /usr/local/etc/pkg.conf was used and reference to a PACKAGESITE was made. This might still work but it'll complain.
1416 pkg: PACKAGESITE in pkg.conf is deprecated. Please create a repository configuration file
1417 Updating repository catalogue
1418 pkg: Warning: use of http:// URL scheme with SRV records is deprecated: switch to pkg+http://
1420 Insead, listen to the errors. Throw an octothorpe in front of that packagesite line, save it, and move on.
1422 Go to /usr/local/etc/pkg/repos/
1424 You should see something like this with an ls
1426 df-latest.conf.sample df-releases.conf.sample
1428 cp or mv one of them to be .conf
1430 edit the one you choose and make the following changes. (I edited the latest version)
1433 url : pkg+http://mirror-master.dragonflybsd.org/dports/${ABI}/L\
1436 signature_type : NONE,
1438 fingerprints : /usr/share/fingerprints,
1442 Depending on when and how you installed and/or upgraded, you may have to chmod 644 the file first to be able to edit it.
1444 ## Basic pkgng Operations
1446 Usage information for __pkgng__ is available in the pkg(8) manual page, or by running `pkg` without additional arguments.
1448 Each __pkgng__ command argument is documented in a command-specific manual page. To read the manual page for `pkg install`, for example, run either:
1453 ## Obtaining Information About Installed Packages with pkgng
1455 Information about the packages installed on a system can be viewed by running `pkg info`. Similar to pkg_info(1), the package version and description for all packages will be listed. Information about a specific package is available by running:
1457 # pkg info packagename
1459 For example, to see which version of __pkgng__ is installed on the system, run:
1462 pkg-1.0.12 New generation package manager
1464 ## Installing and Removing Packages with pkgng
1466 In general, most DragonFly users will install binary packages by typing:
1468 # pkg install <packagename>
1470 For example, to install curl:
1474 Updating repository catalogue
1475 Repository catalogue is up-to-date, no need to fetch fresh copy
1476 The following packages will be installed:
1478 Installing ca_root_nss: 3.13.5
1479 Installing curl: 7.24.0
1481 The installation will require 4 MB more space
1483 1 MB to be downloaded
1485 Proceed with installing packages [y/N]: y
1486 ca_root_nss-3.13.5.txz 100% 255KB 255.1KB/s 255.1KB/s 00:00
1487 curl-7.24.0.txz 100% 1108KB 1.1MB/s 1.1MB/s 00:00
1488 Checking integrity... done
1489 Installing ca_root_nss-3.13.5... done
1490 Installing curl-7.24.0... done
1492 The new package and any additional packages that were installed as dependencies can be seen in the installed packages list:
1495 ca_root_nss-3.13.5 The root certificate bundle from the Mozilla Project
1496 curl-7.24.0 Non-interactive tool to get files from FTP, GOPHER, HTTP(S) servers
1497 pkg-1.0.12 New generation package manager
1499 Packages that are no longer needed can be removed with `pkg delete`. For example, if it turns out that curl is not needed after all:
1502 The following packages will be deleted:
1506 The deletion will free 3 MB
1508 Proceed with deleting packages [y/N]: y
1509 Deleting curl-7.24.0_1... done
1511 ## Upgrading Installed Packages with pkgng
1513 Packages that are outdated can be found with `pkg version`. If a local ports tree does not exist, pkg-version(8) will use the remote repository catalogue, otherwise the local ports tree will be used to identify package versions.
1515 Packages can be upgraded to newer versions with __pkgng__. Suppose a new version of curl has been released. The local package can be upgraded to the new version:
1518 Updating repository catalogue
1519 repo.txz 100% 297KB 296.5KB/s 296.5KB/s 00:00
1520 The following packages will be upgraded:
1522 Upgrading curl: 7.24.0 -> 7.24.0_1
1524 1 MB to be downloaded
1526 Proceed with upgrading packages [y/N]: y
1527 curl-7.24.0_1.txz 100% 1108KB 1.1MB/s 1.1MB/s 00:00
1528 Checking integrity... done
1529 Upgrading curl from 7.24.0 to 7.24.0_1... done
1531 ## Auditing Installed Packages with pkgng
1533 Occasionally, software vulnerabilities may be discovered in software within DPorts. __pkgng__ includes built-in auditing. To audit the software installed on the system, type:
1537 # Advanced pkgng Operations
1539 ## Automatically Removing Leaf Dependencies with pkgng
1541 Removing a package may leave behind unnecessary dependencies, like `security/ca_root_nss` in the example above. Such packages are still installed, but nothing depends on them any more. Unneeded packages that were installed as dependencies can be automatically detected and removed:
1544 Packages to be autoremoved:
1547 The autoremoval will free 723 kB
1549 Proceed with autoremoval of packages [y/N]: y
1550 Deinstalling ca_root_nss-3.13.5... done
1552 ## Backing Up the pkgng Package Database
1554 __pkgng__ includes its own package database backup mechanism. To manually back up the package database contents, type:
1556 # pkg backup -d <pkgng.db>
1558 Additionally, __pkgng__ includes a periodic(8) script to automatically back up the package database daily if `daily_backup_pkgng_enable` is set to `YES` in periodic.conf(5). To prevent the `pkg_install` periodic script from also backing up the package database, set `daily_backup_pkgdb_enable` to `NO` in periodic.conf(5).
1560 To restore the contents of a previous package database backup, run:
1562 # pkg backup -r </path/to/pkgng.db>
1564 ## Removing Stale pkgng Packages
1566 By default, __pkgng__ stores binary packages in a cache directory as defined by `PKG_CACHEDIR` in pkg.conf(5). When upgrading packages with pkg upgrade, old versions of the upgraded packages are not automatically removed.
1568 To remove the outdated binary packages, type:
1572 ##Modifying pkgng Package Metadata
1574 __pkgng__ has a built-in command to update package origins. For example, if `lang/php5` was originally at version 5.3, but has been renamed to lang/php53 for the inclusion of version 5.4, the package database can be updated to deal with this. For __pkgng__, the syntax is:
1576 # pkg set -o <category/oldport>:<category/newport>
1578 For example, to change the package origin for the above example, type:
1580 # pkg set -o lang/php5:lang/php53
1582 As another example, to update lang/ruby18 to lang/ruby19, type:
1584 # pkg set -o lang/ruby18:lang/ruby19
1586 As a final example, to change the origin of the libglut shared libraries from graphics/libglut to graphics/freeglut, type:
1588 # pkg set -o graphics/libglut:graphics/freeglut
1590 _Note_: When changing package origins, in most cases it is important to reinstall packages that are dependent on the package that has had the origin changed. To force a reinstallation of dependent packages, type:
1592 # pkg install -Rf graphics/freeglut
1594 # Building DPorts from source
1596 The average user will probably not build packages from source. However, it's easy to do and it can be done even when packages have already been pre-installed on the system. Common reasons to build from source are:
1598 * The port is new and there's no pre-binary available yet
1599 * The pre-built binaries use the default options and the user needs a package built with a different set of options
1600 * Testing FreeBSD port in order to patch them and submit to DPorts
1601 * The user just prefers building from source
1603 ## Installing DPorts tree
1605 DragonFly 3.4 or later is the minimum version that can build DPorts from source.
1607 It's probably that pkgsrc binaries are already installed because it comes bootstrapped with new systems. It is necessary to rename `/usr/pkg` directory so that the existing pkgsrc binary tools and libraries don’t get accidentally used while building DPorts, causing breakage. For the installation of the DPorts tree, type:
1610 # make dports-create-shallow
1612 If the `/usr/pkg directory` has already been renamed, `git` won’t be in the search path any more. One option is to download a tarball of DPorts and unpack it. To do this, type:
1615 # make dports-download
1617 For future updates, pull delta changes via `git` is fastest, so it is suggested to convert the static tree to a git repository by typing:
1619 # cd /usr/dports/devel/git
1622 # rm -rf /usr/dports
1623 # make dports-create-shallow
1625 The git repository is hosted on the [github account of John Marino](https://github.com/jrmarino/DPorts/#readme).
1629 Building from source works similar to ports and pkgsrc: cd into the appropriate program's directory, and type 'make'. 'make install' to install the software, 'make clean' to clean up work files, and so on. Use 'make config-recursive' if you want to set all the port's options, and the options of its dependencies, immediately instead of during the build.
1631 To take all the default build options and avoid getting the pop-up dialog box, set `NO_DIALOG=yes` on either the command line or the make.conf file.
1633 If you just want to set the options for one package, and accept the default for all of its dependencies, do 'make config' in the package in you want non-default options, and then 'make NO_DIALOG=yes'. Note that this is only necessary if you want to build from source with a non-default set of options, or if no pre-built binary package is available yet.
1636 * How fix/add broken ports: [[docs/howtos/fixdports]]
1637 * [Trick: How to get i386-only software via dports](http://leaf.dragonflybsd.org/mailarchive/users/2013-06/msg00023.html)
1641 DragonFly, up to and including version 3.4, used pkgsrc to manage third party software packages. DragonFly switched to dports at the 3.6 release.
1643 This page is still useful for anyone wanting to use pkgsrc, but the recommended packaging method is dports, which is covered in a similar document here:
1645 [http://www.dragonflybsd.org/docs/howtos/HowToDPorts/](http://www.dragonflybsd.org/docs/howtos/HowToDPorts/)
1649 # pkgsrc on DragonFly
1651 DragonFly uses a specially crafted Makefile in /usr and a git mirror
1652 of the official pkgsrc repository to make pkgsrc distribution more user-friendly.
1654 The basics of the pkgsrc system can be found in NetBSD's [Pkgsrc Guide](http://www.netbsd.org/docs/pkgsrc/), and can be considered the canonical resource.
1661 [Pkgsrc](http://www.pkgsrc.org) is a packaging system that was originally created for NetBSD. It has been ported to DragonFly, along with other operating systems. Pkgsrc is very similar to FreeBSD's ports mechanism.
1665 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.
1667 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.
1669 **Binary Package Benefits**
1671 * A compressed package tarball is typically smaller than the compressed tarball containing the source code for the application.
1673 * 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.
1675 * Packages do not require any understanding of the process involved in compiling software on DragonFly.
1677 **Pkgsrc source Benefits**
1679 * 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.
1681 * 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.
1683 * The licensing conditions of some software distributions forbid binary distribution. They must be distributed as source code.
1685 * 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.
1687 * If you have local patches, you will need the source in order to apply them.
1689 * Some people like having code around, so they can read it if they get bored, hack it, debug crashes, borrow from it (license permitting, of course), and so on.
1691 To keep track of pkgsrc releases subscribe to the [NetBSD pkgsrc users mailing list](http://www.netbsd.org/MailingLists/pkgsrc-users) and the [NetBSD pkgsrc users mailing list](http://www.netbsd.org/MailingLists/tech-pkgsrc). It's also useful to watch the [DragonFly User related mailing list](http://leaf.dragonflybsd.org/mailarchive/) as errors with pkgsrc on DragonFly should be reported there.
1693 **Warning:** Before installing any application, you should check http://www.pkgsrc.org/ for security issues related to your application.
1695 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.
1697 **Note:** Binary packages and source packages are effectively the same software and can be manipulated with the same pkg_* tools.
1699 ## Installing pkgsrc
1701 The basic pkgsrc tools are provided with every DragonFly system as part of installation. However, you still need to download the pkgsrc tree for building applications with these tools.
1703 Set GITHOST in /etc/make.conf or set it as an environment variable to select a different download location, if desired. See mirrors page for available mirrors.
1705 This downloads the stable version of the pkgsrc tree from the default mirror, if you didn't set GITHOST. As root:
1708 # make pkgsrc-create
1710 to fetch the intial pkgsrc repository from the net, or
1713 # make pkgsrc-update
1717 **Note**: If your DragonFly install is not up to date, you might have ended up with an old release of the pkgsrc tree.
1722 will show what release you are on. See Tracking the stable branch for more information.
1724 ### Tracking the stable branch
1726 There are quarterly releases of pkgsrc that are specifically designed for stability. You should in general follow these, rather than the bleeding edge pkgsrc. When a new branch is out you need to set up a local branch tracking that one. 'make pkgsrc-update' will not do this for you.
1728 To see the available remote branches:
1734 To create a local branch, tracking the remote quarterly release:
1737 # git branch pkgsrc-2010Q4 origin/pkgsrc-2010Q4
1739 Branch naming format is 'pkgsrc-YYYYQX', where YYYY is the year and QX is quarters 1-4 of the year. Check [pkgsrc.org](http://www.pkgsrc.org/) to see the name of the latest stable branch.
1741 After adding a new branch, it can be downloaded with:
1744 # git checkout pkgsrc-2010Q4
1747 ## Dealing with pkgsrc packages
1749 The following section explains how to find, install and remove pkgsrc packages.
1751 ### Finding Your Application
1753 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:
1755 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.
1758 fvwm-2.4.20nb1 Newer version of X11 Virtual window manager
1759 fvwm-2.5.24 Development version of X11 Virtual window manager
1760 fvwm-themes-0.6.2nb8 Configuration framework for fvwm2 with samples
1761 fvwm-wharf-1.0nb1 Copy of AfterStep's Wharf compatible with fvwm2
1762 fvwm1-1.24rnb1 Virtual window manager for X
1764 # pkg_search -v fvwm-2.5
1765 Name : fvwm-2.5.24-50
1767 Desc : Development version of X11 Virtual window manager
1769 Deps : perl>#5.0 gettext-lib>0.14.5 [...]
1771 Its also possible to issue the command
1774 # bmake search key='package you are looking for'
1776 from the `/usr/pkgsrc` directory.
1778 It's also possible to browse website that show all the available pkgsrc packages, such as [http://pkgsrc.se/](http://pkgsrc.se) .
1780 ### Installing applications
1782 Downloading a binary package is almost always faster than building from source, but not all programs in pkgsrc can be redistributed as a binary. In most cases, you will want to download a binary package if possible, and otherwise build from source if it's not available.
1784 The `bin-install` target on DragonFly (with pkgsrc from 2011/02/07 and later) will do just that:
1786 # cd /usr/pkgsrc/misc/screen
1787 # bmake bin-install clean
1789 This will download and install the appropriate `screen` binary package if it exists, and try building from source if it can't complete the download.
1791 ### Installing applications, source only
1793 Packages are built by going into the appropriate directory and issuing `bmake install clean`. For example, to build the *screen* package you need to issue the following commands.
1795 # cd /usr/pkgsrc/misc/screen
1796 # bmake install clean
1798 To find out the options that can affect how a program is built:
1800 # bmake show-options
1804 # bmake PKG_OPTIONS.<package_name>="-option1 option2" install clean
1806 Listing an option enables it. Listing an option with a "-" before it disables the option.
1808 To make these option changes permanent for every future build or upgrade of this package, put a similar line in `/usr/pkg/etc/mk.conf`:
1810 . PKG_OPTIONS.<package_name>=-option1 option2
1812 ### Installing applications, binary only
1814 Binary packages can be installed using *pkg_radd*:
1818 This program works by setting the `PKG_PATH` environment variable to the appropriate path for the operating system and architecture to a remote repository of binary packages, and then using *pkg_add* to get packages. This will install most packages, but will not upgrade packages that are already installed.
1820 You can manually set `BINPKG_BASE` and use *pkg_add* to get the same effect, using a different server.
1822 # setenv BINPKG_BASE http://mirror-master.dragonflybsd.org/packages
1825 #### Issues with pre-built packages
1827 * The default remote repository for binary packages tracks quarterly pkgsrc releases, so your local install of pkgsrc should be the same quarterly release.
1828 * Some packages are not licensed for distribution in binary form, so they may be able to build on DragonFly but won't be available with *pkg_radd*. If it fails, try going to that package's directory and install the package manually as described above.
1829 * If you upgrade to an new DEVELOPMENT version of DragonFly very early (i.e. shortly after the branch), it might be possible that *pkg_radd* fails to install packages. This is due the fact, that it takes some time to built binary packages and thus, there are no binary packages available on the mirrors yet. Usually you'll see an announcement on the lists once the first packages for DEVELOPMENT are ready.
1831 ### List all installed applications
1833 To obtain a list of all the packages that are installed on your system:
1837 To see if certain packages have been installed, filter for the name of the package. This example will show all *xorg*-related packages currently installed on the system:
1839 # pkg_info | grep xorg
1841 ### Removing packages
1843 If a program was installed as a package:
1845 # pkg_delete packagename
1847 If a package was installed from the source files, you can also change to the directory they were installed from and issue the command:
1851 Note that these methods are effectively interchangeable. Either will work whether the package was originally installed from source or binary.
1853 #### Remove associated files needed for building a package
1855 To remove the work file from building a package, and the package's dependencies:
1857 # bmake clean clean-depends
1859 This can be combined with other steps:
1861 # bmake install clean clean-depends
1863 ## Upgrading packages
1865 There's a number of ways to upgrade pkgsrc; some of these are built in and some are packages installable with pkgsrc. This list is not necessarily comprehensive.
1867 ### Update pkgsrc system packages
1869 **Note**: Sometimes basic pkgsrc tools; *bmake*, *pkg_install* and *bootstrap-mk-files* need to be upgraded. However, they can't be deleted and replaced since you need that tool to accomplish replacement. The solution is to build a separate package before deletion, and install that package.
1871 # cd /usr/pkgsrc/devel/bmake
1873 # cd /usr/pkgsrc/pkgtools/pkg_install
1875 # cd /usr/pkgsrc/pkgtools/bootstrap-mk-files
1877 # env USE_DESTDIR=yes bmake package
1878 # bmake clean-depends clean
1880 And go to the packages directory and install the binary package with
1882 # cd /usr/pkgsrc/packages/All
1883 # pkg_add -u <pkg_name> (i.e. the name of the .tgz file).
1886 Performed in the `/usr/pkgsrc` directory that correlates with the installed package, the software is first built and then replaced.
1888 # cd /usr/pkgsrc/chat/ircII
1891 ### pkg_rolling-replace
1893 *pkg_rolling-replace* replaces packages one by one and you can use it for a better way of package management. Actually it does `bmake replace` on one package at a time, sorting the packages being replaced according to their interdependencies, which avoids most duplicate rebuilds. Once *pkg_rolling-replace* is installed you can update the packages through the following steps.
1895 # cd /usr && make pkgsrc-update
1896 # pkg_rolling-replace -u
1900 Downloads and installs binary packages. Check the [[mirrors]] page for sites carrying binary packages to use with pkgin. You can run the following commands to get the packages updated. This assumes that *pkgin* is already configured. Please consult the documentation and the man page on how to do so.
1903 # pkgin full-upgrade
1907 It updates packages by removing them and rebuilding them. Warning: programs are unavailable until a rebuild finishes. If they don't rebuild, it won't work. *pkg_chk* requires a few steps in order to work correctly. They are listed here.
1909 # pkg_chk -g # make initial list of installed packages
1910 # pkg_chk -r # remove all packages that are not up to date and packages that depend on them
1911 # pkg_chk -a # install all missing packages (use binary packages, this is the default)
1912 # pkg_chk -as # install all missing packages (build from source)
1914 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.
1918 Point at a local or online binary archive location to download and update packages.
1922 This requires that you've set up rpkgmanager first. Read more about rpkgmanager [[here|docs/howtos/rpkgmanager/]].
1924 # yes | rpkgmanager.rb
1926 ## Start pkgsrc applications on system startup
1928 Packages often install rc.d scripts to control software running on startup. To specify where the rc.d scripts from the installed packages should go, add the following lines to your `/usr/pkg/etc/mk.conf` file:
1930 RCD_SCRIPTS_DIR=/etc/rc.d
1933 This option can be set in the environment to activate it for binary packages. These packages will still have to be enabled in `/etc/rc.conf/` to run at boot. If these options aren't set, the rc file will be placed in `/usr/pkg/share/examples/rc.d/` and will need to be manually copied over to `/etc/rc.d`.
1935 Many other options can be set in this file; see `/usr/pkgsrc/mk/defaults/mk.conf` for examples.
1937 ## Miscellaneous topics
1939 ### Post-installation Activities
1941 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.
1942 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:
1944 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
1946 # pkg_info -L foopackage-1.0.0 | less
1948 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
1950 # pkg_info | grep -i foopackage
1952 will find all the installed packages that have *foopackage* in the package name. Replace *foopackage* in your command line as necessary.
1954 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. 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
1956 # pkg_info foopackage-1.0.0
1958 A `WWW:` line, if present, should provide a URL for the application's web site.
1960 ### Dealing with Broken Packages
1962 If you come across a package that does not work for you, there are a few things you can do, including:
1964 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!
1966 1. Send email to the maintainer of the package first. Type `bmake maintainer` or read the `Makefile` to find the maintainer's email address. Remember to include the name and version of the port (send the `$NetBSD:` line from the `Makefile`) and the output leading up to the error when you email the maintainer. If you do not get a response from the maintainer, you can try [users](http://leaf.dragonflybsd.org/mailarchive/) .
1968 1. Grab a pre-built package from an [[mirror|mirrors]] site near you.
1972 Packages that can be built within the pkgsrc framework but are not yet necessarily ready for production use can be found in [http://pkgsrc-wip.sourceforge.net](http://pkgsrc-wip.sourceforge.net). These packages need to be downloaded separately; check the website for details. Packages in this collection are in development and may not build successfully.
1976 * More information: The pkgsrc guide [http://www.netbsd.org/Documentation/pkgsrc/](http://www.netbsd.org/Documentation/pkgsrc/)
1978 * Web interface for searching packages: [http://www.pkgsrc.se](http://www.pkgsrc.se)
1980 * Ways to upgrade packages [http://wiki-static.aydogan.net/How_to_upgrade_packages](http://wiki-static.aydogan.net/How_to_upgrade_packages)
1982 * To search and/or report bugs against packages in pkgsrc, look at [http://www.netbsd.org/support/send-pr.html](http://www.netbsd.org/support/send-pr.html) - use category 'pkg'.
1984 * The #pkgsrc IRC channel on Freenode
1986 * The #dragonflybsd IRC channel on EFnet
1988 # The X Window System
1989 ***Updated for X.Org's X11 server by Ken Tom and Marc Fonvieille. Updated for DragonFly by Victor Balada Diaz. Updated for 2014 pkgng by Warren Postma***
1995 This chapter will cover the installation and some configuration of the usual way of giving your Dragonfly BSD system an X-Windows style Graphical User Interface (GUI) and a modern Desktop Environment. In Unix systems, the graphical drawing system is provided by the combination of an X11R6 compliant X-Windows Server, such as the X.org server, and other software such as Window Managers and Desktop Environments. This multi-layered approach may be surprising to people coming from systems like the Mac or like Windows where these components are not so flexible, or provided by so many separately installed and configured pieces.
1997 For more information on the video hardware support in X.org, check the [X.org](http://www.x.org/) web site. If you have problems configuring your X server, just search the web. There are lots of tutorials and guides on how to set up your X properly, if the information in this page is not enough for your situation.
1999 Before reading this chapter, you should know how to install additional third-party software. Read the `dports` section of the documentation, for DragonFly 3.4 and later.
2001 You may find the FreeBSD X Configuration instructions apply exactly and unchanged in DragonFly BSD.
2002 They are found [[here|http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/x-config.html]]
2008 X.Org is the most popular free implementation of the X11 specification. The X11 specification is an open standard, and there are other implementations, some commercial, and some free.
2010 ### The Window Manager and the Desktop Environment
2012 An X Server is a very low level piece of software. It does not provide any way to move windows around or resize them. It does not provide a title bar on the top of your windows, or a dock, or any menus.
2014 These things are the job, in the oldest style of X environment, of your window manager, or in more recent times, of a Desktop Environment.
2016 Installing X.org by itself does not give you any window manager or any desktop environment. You will have to choose one and install it yourself. Until you select one, your system will not be usable.
2018 There are dozens of window managers and desktop environments available for X. The most retro ones you might chose include `fvwm` and `twm` which have that retro 1980s workstation look and feel. There are also window managers included inside modern desktop environments like XFCE, KDE and Gnome.
2020 If you are brand new and don't know what to do, select the XFCE4 desktop and follow those instructions.
2021 Every desktop environment and window manager also has a different configuration mechanism. Read your chosen environment's documentation to learn more. Some are configured by text files alone, and some (like KDE and Gnome) have sophisticated graphical configuration utilities and "control panels".
2023 Note that XFCE4 and Gnome and KDE do not require you to install any window manager as they include one automatically.
2027 **X.org** is currently available in the DragonFly dports collection.
2031 pkg install xorg-7.7
2033 By the time you read this, it might be a newer version of xorg than 7.7, you can also try this general command:
2039 You may need to add the following lines to `/etc/rc.conf` for regular PCs but you might not want to set these two lines to NO instead on a Virtual Machine as they cause problems in Dragonfly BSD 3.4 through 3.6:
2044 Also see below about enabling `moused` in rc.conf, which may be required for you to see your mouse pointer in X.
2046 As of version 7.3, Xorg can often work without any configuration file by simply typing at prompt:
2052 If this does not work, or if the default configuration is not acceptable, then X11 must be configured manually. For example, if X11 does not detect your mouse then you will not get a mouse pointer, you will get a desktop (either a color or a dotted-pattern) but moving your mouse will not result in you seeing a mouse pointer move around. Also, you might get a garbled display, or no display at all. If any of these happen to you, you need to do some manual configuration of X.org, which means a configuration text file.
2054 Configuration of X11 is a multi-step process. The first step is to build an initial configuration file. As the super user, simply run:
2059 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.
2061 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:
2065 # Xorg -config xorg.conf.new -retro
2067 The -retro option is now required or you will only get a black desktop when testing. This retro mode is an empty X desktop with a dot pattern on the background and an X cursor in the center. If the mouse is working, you should be able to move it.
2069 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.
2071 **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`:
2075 Tune the `xorg.conf.new` configuration file to taste and move it to where [Xorg(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=xorg§ion=1) can find it. This is typically `/etc/X11/xorg.conf` or `/usr/pkg/xorg/lib/X11/xorg.conf`.
2079 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).
2081 ## The X Display Manager
2083 ***Contributed by Seth Kingsley.***
2087 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.
2089 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.
2093 The **XDM** daemon program is located in `/usr/pkg/bin/xdm`. This program can be run at any time as `root` and it will start managing the X display on the local machine. If **XDM** is to be run every time the machine boots up, a convenient way to do this is by adding an entry to `/etc/ttys`. For more information about the format and usage of this file, see [ Section 17.3.2.1](term.html#TERM-ETCTTYS). There is a line in the default `/etc/ttys` file for running the **XDM** daemon on a virtual terminal:
2097 ttyv8 "/usr/pkg/bin/xdm -nodaemon" xterm off secure
2099 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.
2103 The **XDM** configuration directory is located in `/var/lib/xdm`. The sample configuration files are in `/usr/pkg/share/examples/xdm/`, in this directory there are several files used to change the behavior and appearance of **XDM** . Typically these files will be found:
2106 <tablestyle="width:100%"> **File** | **Description**
2107 <tablestyle="width:100%"> `Xaccess` | Client authorization ruleset.
2108 `Xresources` | Default X resource values.
2109 `Xservers` | List of remote and local displays to manage.
2110 `Xsession` | Default session script for logins.
2111 `Xsetup_`* | Script to launch applications before the login interface.
2112 `xdm-config` | Global configuration for all displays running on this machine.
2113 `xdm-errors` | Errors generated by the server program.
2114 `xdm-pid` | The process ID of the currently running XDM. |
2118 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).
2120 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.
2124 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.
2128 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.
2132 This is a list of the remote displays the chooser should provide as choices.
2136 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.
2140 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`.
2144 This contains settings in the form of app-defaults that are applicable to every display that this installation manages.
2148 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.
2150 ### Running a Network Display Server
2152 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:
2156 ! SECURITY: do not listen for XDMCP or Chooser requests
2158 ! Comment out this line if you want to manage X terminals with xdm
2160 DisplayManager.requestPort: 0
2162 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.
2164 ### Replacements for XDM
2166 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.
2170 ## Desktop Environments
2172 ***Contributed by Valentino Vaschetto. ***
2174 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** .
2180 **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.
2182 #### Installing GNOME
2184 **GNOME** can be easily installed from a package or from the pkgsrc framework:
2186 To install the **GNOME** package from the network, simply type:
2188 # pkg install gnome-desktop
2190 To build **GNOME** from source, if you have the pkgsrc tree on your system:
2192 # cd /usr/pkgsrc/meta-pkgs/gnome
2194 # bmake install clean
2196 Once **GNOME** is installed, the X server must be told to start **GNOME** instead of a default window manager.
2198 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.
2200 **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:
2204 % echo "/usr/pkg/bin/gnome-session" > ~/.xinitrc
2206 Next, type `startx`, and the **GNOME** desktop environment will be started.
2208 **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** :
2212 % echo "#!/bin/sh" > ~/.xsession
2214 % echo "/usr/pkg/bin/gnome-session" >> ~/.xsession
2216 % chmod +x ~/.xsession
2218 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** .
2220 #### Anti-aliased Fonts with GNOME
2222 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).
2224 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.
2230 **KDE** is an easy to use contemporary desktop environment. Some of the things that **KDE** brings to the user are:
2232 * A beautiful contemporary desktop
2234 * A desktop exhibiting complete network transparency
2236 * An integrated help system allowing for convenient, consistent access to help on the use of the **KDE** desktop and its applications
2238 * Consistent look and feel of all **KDE** applications
2240 * Standardized menu and toolbars, keybindings, color-schemes, etc.
2242 * Internationalization: **KDE** is available in more than 40 languages
2244 * Centralized consisted dialog driven desktop configuration
2246 * A great number of useful **KDE** applications
2248 **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/).
2252 Just as with **GNOME** or any other desktop environment, the easiest way to install **KDE** is through the pkgsrc framework or from a package:
2254 To install the **KDE** 4.10 package from the network, simply type:
2256 # pkg install kde-4.10
2258 To build **KDE** from source, using the pkgsrc framework:
2260 # cd /usr/pkgsrc/meta-pkgs/kde3
2262 # bmake install clean
2264 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:
2266 % echo "exec startkde" > ~/.xinitrc
2268 Now, whenever the X Window System is invoked with `startx`, **KDE** will be the desktop.
2270 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.
2272 #### More Details on KDE
2274 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.
2276 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.
2278 #### The KDE Display Manager
2280 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.
2282 To enable **kdm** , the `ttyv8` entry in `/etc/ttys` has to be adapted. The line should look as follows:
2285 ttyv8 "/usr/pkg/bin/kdm -nodaemon" xterm on secure
2292 **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:
2294 * A simple, easy-to-handle desktop
2296 * Fully configurable via mouse, with drag and drop, etc
2298 * Main panel similar to **CDE** , with menus, applets and applications launchers
2300 * Integrated window manager, file manager, sound manager, **GNOME** compliance module, and other things
2302 * Themeable (since it uses GTK+)
2304 * Fast, light and efficient: ideal for older/slower machines or machines with memory limitations
2306 More information on **XFce** can be found on the [XFce website](http://www.xfce.org/).
2308 #### Installing XFce
2310 A binary package for **XFce** exists. To install, simply type:
2314 This should install the main xfce4 desktop package, and most of the required components.
2316 Alternatively, to build from source, use the pkgsrc framework:
2320 # cd /usr/pkgsrc/meta-pkgs/xfce4
2322 # bmake install clean
2324 Now, tell the X server to launch **XFce** the next time X is started. Simply type this:
2326 % echo "/usr/pkg/bin/startxfce4" > ~/.xinitrc
2328 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).
2330 <!-- XXX: FreeBSD's handbook has a nice user-oriented section about X applications here. maybe we should have one, too -->
2334 # Configuration and Tuning
2336 ***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.***
2342 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.
2344 After reading this chapter, you will know:
2346 * How to efficiently work with file systems and swap partitions.
2348 * The basics of `rc.conf` configuration and `rc.d` startup systems.
2350 * How to configure and test a network card.
2352 * How to configure virtual hosts on your network devices.
2354 * How to use the various configuration files in `/etc`.
2356 * How to tune DragonFly using `sysctl` variables.
2358 * How to tune disk performance and modify kernel limitations.
2360 Before reading this chapter, you should:
2362 * Understand UNIX® and DragonFly basics ([Chapter 3](basics.html)).
2364 * Be familiar with the basics of kernel configuration/compilation ([Chapter 9](kernelconfig.html)).
2366 ## Initial Configuration
2368 ### Partition Layout
2370 #### Base Partitions
2372 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`.
2373 <!-- 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? -->
2375 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.
2377 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.
2379 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.
2383 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.
2384 <!-- XXX: do we really recommend double the RAM for swap? IMHO the amount of RAM should be more than enough -->
2386 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.
2390 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`.
2392 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.
2393 <!-- XXX: again, same story about the edges of disks... -->
2397 CategoryHandbook-configuration
2399 ## Core Configuration
2401 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.
2403 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.
2405 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.
2407 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:
2411 hostname="node15.example.com"
2413 network_interfaces="fxp0 lo0"
2415 ifconfig_fxp0="inet 10.1.1.1"
2421 defaultrouter="10.1.1.254"
2429 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.
2431 Upgrading the system using `make world` will not overwrite the `rc.conf` file, so system configuration information will not be lost.
2435 CategoryHandbook-configuration
2437 ## Application Configuration
2439 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.
2441 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.
2443 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.
2445 For example, consider the contents of the directory `/usr/pkg/etc/httpd`:
2451 -rw-r--r-- 1 root wheel - 34K Jan 11 12:04 httpd.conf
2453 -rw-r--r-- 1 root wheel - 13K Jan 11 12:02 magic
2455 -rw-r--r-- 1 root wheel - 28K Jan 11 12:02 mime.types
2457 -rw-r--r-- 1 root wheel - 11K Jan 11 12:02 ssl.conf
2465 ## Starting Services
2467 It is common for a system to host a number of services. These may be started in several different fashions, each having different advantages.
2469 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.
2471 A generic startup script in `/usr/pkg/share/examples/rc.d` looks like:
2491 kill -9 `cat /var/run/foobar.pid`
2498 echo "Usage: `basename $0` {start|stop}" >&2
2512 <!-- XXX: I don't think we actually look in /usr/pkg/share/examples/rc.d -->
2514 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:
2518 # chmod 755 "FooBar.sh"
2520 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.
2522 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.
2524 **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.
2526 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.
2528 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.
2532 CategoryHandbook-configuration
2534 ## Configuring the cron Utility
2536 <!-- XXX: can't really comment on this. someone please revise it -->
2538 ***Contributed by Tom Rhodes. ***
2540 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.
2542 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.
2544 **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.
2546 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`.
2548 Let us take a look at the `/etc/crontab` file (the system crontab):
2552 # /etc/crontab - root's crontab for DragonFly
2562 PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin (2)
2570 #minute hour mday month wday who command (3)
2577 */5 * * * * root /usr/libexec/atrun (4)
2579 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.
2581 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.
2583 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.
2585 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.
2587 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.
2589 ### Installing a Crontab
2591 **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.
2593 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:
2597 % crontab crontab-file
2599 In this example, `crontab-file` is the filename of a `crontab` that was previously created.
2601 There is also an option to list installed `crontab` files: just pass the `-l` option to `crontab` and look over the output.
2603 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.
2605 If you later want to remove your user `crontab` completely, use `crontab` with the `-r` option.
2607 ## Using rc under DragonFly
2609 ***Contributed by Tom Rhodes. ***
2611 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:
2615 # /etc/rc.d/sshd restart
2617 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`:
2621 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.
2623 Another way to add services to the automatic startup/shutdown is to type, for example for `natd`,
2627 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:
2631 # /etc/rc.d/sshd forcerestart
2633 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:
2637 # /etc/rc.d/sshd rcvar
2643 **Note:** The second line (`# sshd`) is the output from the `rc.d` script, not a `root` prompt.
2645 To determine if a service is running, a `status` option is available. For instance to verify that `sshd` is actually started:
2649 # /etc/rc.d/sshd status
2651 sshd is running as pid 433.
2653 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.
2655 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.
2657 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:
2659 * `PROVIDE`: Specifies the services this file provides.
2661 * `REQUIRE`: Lists services which are required for this service. This file will run ***after*** the specified services.
2663 * `BEFORE`: Lists services which depend on this service. This file will run ***before*** the specified services.
2665 * 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.
2667 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.
2669 By using this method, an administrator can easily control system services without the hassle of ***runlevels*** like some other UNIX® operating systems.
2671 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.
2673 ### Using DragonFly's rcrun(8)
2675 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)
2677 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.
2679 The remaining commands are:
2682 **disable** | Sets the corresponding `_enable` variable in rc.conf(5) to ***NO*** and runs the stop command.
2683 **enable** | Sets the corresponding `_enable` variable in rc.conf(5) to ***YES*** and runs the start command.
2684 **list** | Shows the status of the specified scripts. If no argument is specified, the status of all scripts is shown. |
2688 To enable the [dntpd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=dntpd§ion=8) service, you can use:
2694 To check if [dntpd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=dntpd§ion=8) is running you can use the following command:
2702 To start [dntpd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=dntpd§ion=8):
2708 Running /etc/rc.d/dntpd start
2712 Restart and stop works the same way:
2728 If a service is not enabled in `/etc/rc.conf`, but you want it start anyway, execute the following:
2734 Running /etc/rc.d/dntpd forcestart
2741 <tablestyle="width:100%"> [(1)](configtuning-rcng.html#AEN4751) | Previously this was used to define *BSD dependent features.
2746 ## Setting Up Network Interface Cards
2748 ***Contributed by Marc Fonvieille. ***
2750 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.
2752 ### Locating the Correct Driver
2754 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.
2756 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.
2758 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:
2762 dc0: <82c169 PNIC 10/100BaseTX> port 0xa000-0xa0ff mem 0xd3800000-0xd38
2764 000ff irq 15 at device 11.0 on pci0
2766 dc0: Ethernet address: 00:a0:cc:da:da:da
2768 miibus0: <MII bus> on dc0
2770 ukphy0: <Generic IEEE 802.3u media interface> on miibus0
2772 ukphy0: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto
2774 dc1: <82c169 PNIC 10/100BaseTX> port 0x9800-0x98ff mem 0xd3000000-0xd30
2776 000ff irq 11 at device 12.0 on pci0
2778 dc1: Ethernet address: 00:a0:cc:da:da:db
2780 miibus1: <MII bus> on dc1
2782 ukphy1: <Generic IEEE 802.3u media interface> on miibus1
2784 ukphy1: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto
2786 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.
2788 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.
2790 ### Configuring the Network Card
2792 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.
2794 To display the configuration for the network interfaces on your system, enter the following command:
2800 dc0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
2802 inet 192.168.1.3 netmask 0xffffff00 broadcast 192.168.1.255
2804 ether 00:a0:cc:da:da:da
2806 media: Ethernet autoselect (100baseTX <full-duplex>)
2810 dc1: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
2812 inet 10.0.0.1 netmask 0xffffff00 broadcast 10.0.0.255
2814 ether 00:a0:cc:da:da:db
2816 media: Ethernet 10baseT/UTP
2820 lp0: flags=8810<POINTOPOINT,SIMPLEX,MULTICAST> mtu 1500
2822 lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> mtu 16384
2824 inet 127.0.0.1 netmask 0xff000000
2826 tun0: flags=8010<POINTOPOINT,MULTICAST> mtu 1500
2828 **Note:** Note that entries concerning IPv6 (`inet6` etc.) were omitted in this example.
2830 In this example, the following devices were displayed:
2832 * `dc0`: The first Ethernet interface
2834 * `dc1`: The second Ethernet interface
2836 * `lp0`: The parallel port interface
2838 * `lo0`: The loopback device
2840 * `tun0`: The tunnel device used by **ppp**
2842 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.
2844 In this example, the `dc0` device is up and running. The key indicators are:
2846 1. `UP` means that the card is configured and ready.
2848 1. The card has an Internet (`inet`) address (in this case `192.168.1.3`).
2850 1. It has a valid subnet mask (`netmask`; `0xffffff00` is the same as `255.255.255.0`).
2852 1. It has a valid broadcast address (in this case, `192.168.1.255`).
2854 1. The MAC address of the card (`ether`) is `00:a0:cc:da:da:da`
2856 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.
2858 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.
2860 If the [ifconfig(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=ifconfig§ion=8) output had shown something similar to:
2864 dc0: flags=8843<BROADCAST,SIMPLEX,MULTICAST> mtu 1500
2866 ether 00:a0:cc:da:da:da
2868 it would indicate the card has not been configured.
2870 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.
2874 # ifconfig dc0 inet 192.168.1.3 netmask 255.255.255.0
2876 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.
2878 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:
2882 ifconfig_dc0="inet 192.168.1.3 netmask 255.255.255.0"
2884 ifconfig_dc1="inet 10.0.0.1 netmask 255.255.255.0 media 10baseT/UTP"
2886 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`.
2888 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.
2890 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`.
2892 ### Testing and Troubleshooting
2894 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.
2896 Once the system has been rebooted, you should test the network interfaces.
2898 #### Testing the Ethernet Card
2900 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.
2902 First test the local interface:
2906 % ping -c5 192.168.1.3
2908 PING 192.168.1.3 (192.168.1.3): 56 data bytes
2910 64 bytes from 192.168.1.3: icmp_seq#0 ttl64 time=0.082 ms
2912 64 bytes from 192.168.1.3: icmp_seq#1 ttl64 time=0.074 ms
2914 64 bytes from 192.168.1.3: icmp_seq#2 ttl64 time=0.076 ms
2916 64 bytes from 192.168.1.3: icmp_seq#3 ttl64 time=0.108 ms
2918 64 bytes from 192.168.1.3: icmp_seq#4 ttl64 time=0.076 ms
2922 --- 192.168.1.3 ping statistics ---
2924 5 packets transmitted, 5 packets received, 0% packet loss
2926 round-trip min/avg/max/stddev = 0.074/0.083/0.108/0.013 ms
2928 Now we have to ping another machine on the LAN:
2932 % ping -c5 192.168.1.2
2934 PING 192.168.1.2 (192.168.1.2): 56 data bytes
2936 64 bytes from 192.168.1.2: icmp_seq#0 ttl64 time=0.726 ms
2938 64 bytes from 192.168.1.2: icmp_seq#1 ttl64 time=0.766 ms
2940 64 bytes from 192.168.1.2: icmp_seq#2 ttl64 time=0.700 ms
2942 64 bytes from 192.168.1.2: icmp_seq#3 ttl64 time=0.747 ms
2944 64 bytes from 192.168.1.2: icmp_seq#4 ttl64 time=0.704 ms
2948 --- 192.168.1.2 ping statistics ---
2950 5 packets transmitted, 5 packets received, 0% packet loss
2952 round-trip min/avg/max/stddev = 0.700/0.729/0.766/0.025 ms
2954 You could also use the machine name instead of `192.168.1.2` if you have set up the `/etc/hosts` file.
2956 #### Troubleshooting
2958 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.
2960 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.
2962 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.
2964 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.
2966 ***`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].
2968 ***`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.
2970 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.
2974 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.
2976 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`.
2978 An alias entry for the interface `fxp0` looks like:
2982 ifconfig_fxp0_alias0="inet xxx.xxx.xxx.xxx netmask xxx.xxx.xxx.xxx"
2984 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.
2986 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`).
2988 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`.
2990 The following entries configure the adapter correctly for this arrangement:
2994 ifconfig_fxp0="inet 10.1.1.1 netmask 255.255.255.0"
2996 ifconfig_fxp0_alias0="inet 10.1.1.2 netmask 255.255.255.255"
2998 ifconfig_fxp0_alias1="inet 10.1.1.3 netmask 255.255.255.255"
3000 ifconfig_fxp0_alias2="inet 10.1.1.4 netmask 255.255.255.255"
3002 ifconfig_fxp0_alias3="inet 10.1.1.5 netmask 255.255.255.255"
3004 ifconfig_fxp0_alias4="inet 202.0.75.17 netmask 255.255.255.240"
3006 ifconfig_fxp0_alias5="inet 202.0.75.18 netmask 255.255.255.255"
3008 ifconfig_fxp0_alias6="inet 202.0.75.19 netmask 255.255.255.255"
3010 ifconfig_fxp0_alias7="inet 202.0.75.20 netmask 255.255.255.255"
3014 CategoryHandbook-configuration
3016 ## Configuration Files
3020 There are a number of directories in which configuration information is kept. These include:
3023 `/etc` | Generic system configuration information; data here is system-specific.
3024 `/etc/defaults` | Default versions of system configuration files.
3025 `/etc/mail` | Extra [sendmail(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=sendmail§ion=8) configuration, other MTA configuration files.
3026 `/etc/ppp` | Configuration for both user- and kernel-ppp programs.
3027 `/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.
3028 `/usr/local/etc` | Configuration files for installed applications. May contain per-application subdirectories.
3029 `/usr/local/etc/rc.d` | Start/stop scripts for installed applications.
3030 `/var/db` | Automatically generated system-specific database files, such as the package database, the locate database, and so on |
3036 #### /etc/resolv.conf
3038 `/etc/resolv.conf` dictates how DragonFly's resolver accesses the Internet Domain Name System (DNS).
3040 The most common entries to `resolv.conf` are:
3043 `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.
3044 `search` | Search list for hostname lookup. This is normally determined by the domain of the local hostname.
3045 `domain` | The local domain name. |
3049 A typical `resolv.conf`:
3055 nameserver 147.11.1.11
3057 nameserver 147.11.100.30
3059 **Note:** Only one of the `search` and `domain` options should be used.
3061 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.
3065 `/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.
3075 # This file should contain the addresses and aliases
3077 # for local hosts that share this file.
3079 # In the presence of the domain name service or NIS, this file may
3081 # not be consulted at all; see /etc/nsswitch.conf for the resolution order.
3087 ::1 localhost localhost.my.domain myname.my.domain
3089 127.0.0.1 localhost localhost.my.domain myname.my.domain
3093 # Imaginary network.
3095 #10.0.0.2 myname.my.domain myname
3097 #10.0.0.3 myfriend.my.domain myfriend
3101 # According to RFC 1918, you can use the following IP networks for
3103 # private nets which will never be connected to the Internet:
3107 # 10.0.0.0 - 10.255.255.255
3109 # 172.16.0.0 - 172.31.255.255
3111 # 192.168.0.0 - 192.168.255.255
3115 # In case you want to be able to connect to the Internet, you need
3117 # real official assigned numbers. PLEASE PLEASE PLEASE do not try
3119 # to invent your own network numbers but instead get one from your
3121 # network provider (if any) or from the Internet Registry (ftp to
3123 # rs.internic.net, directory `/templates').
3127 `/etc/hosts` takes on the simple format of:
3131 [Internet address] [official hostname] [alias1] [alias2] ...
3137 10.0.0.1 myRealHostname.example.com myRealHostname foobar1 foobar2
3139 Consult [hosts(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=hosts§ion=5) for more information.
3141 ### Log File Configuration
3145 `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.
3153 # Spaces ARE valid field separators in this file. However,
3155 # other *nix-like systems still insist on using tabs as field
3157 # separators. If you are sharing this file between systems, you
3159 # may want to use only tabs as field separators here.
3161 # Consult the syslog.conf(5) manual page.
3164 *.err;kern.debug;auth.notice;mail.crit /dev/console
3166 *.notice;kern.debug;lpr.info;mail.crit;news.err /var/log/messages
3168 security.* /var/log/security
3170 mail.info /var/log/maillog
3172 lpr.info /var/log/lpd-errs
3174 cron.* /var/log/cron
3179 *.notice;news.err root
3185 # uncomment this to log all writes to /dev/console to /var/log/console.log
3187 #console.info /var/log/console.log
3189 # uncomment this to enable logging of all log messages to /var/log/all.log
3191 #*.* /var/log/all.log
3193 # uncomment this to enable logging to a remote log host named loghost
3197 # uncomment these if you're running inn
3199 # news.crit /var/log/news/news.crit
3201 # news.err /var/log/news/news.err
3203 # news.notice /var/log/news/news.notice
3208 *.* /var/log/slip.log
3213 *.* /var/log/ppp.log
3215 Consult the [syslog.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=syslog.conf§ion=5) manual page for more information.
3219 `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.
3221 `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.
3225 # configuration file for newsyslog
3231 # filename [owner:group] mode count size when [ZB] [/pid_file] [sig_num]
3233 /var/log/cron 600 3 100 * Z
3235 /var/log/amd.log 644 7 100 * Z
3237 /var/log/kerberos.log 644 7 100 * Z
3239 /var/log/lpd-errs 644 7 100 * Z
3241 /var/log/maillog 644 7 * @T00 Z
3243 /var/log/sendmail.st 644 10 * 168 B
3245 /var/log/messages 644 5 100 * Z
3247 /var/log/all.log 600 7 * @T00 Z
3249 /var/log/slip.log 600 3 100 * Z
3251 /var/log/ppp.log 600 3 100 * Z
3253 /var/log/security 600 10 100 * Z
3255 /var/log/wtmp 644 3 * @01T05 B
3257 /var/log/daily.log 640 7 * @T00 Z
3259 /var/log/weekly.log 640 5 1 $W6D0 Z
3261 /var/log/monthly.log 640 12 * $M1D0 Z
3263 /var/log/console.log 640 5 100 * Z
3265 Consult the [newsyslog(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=newsyslog§ion=8) manual page for more information.
3269 `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.
3271 A sample `sysctl.conf` turning off logging of fatal signal exits and letting Linux programs know they are really running under DragonFly:
3275 kern.logsigexit=0 # Do not log fatal signal exits (e.g. sig 11)
3277 compat.linux.osname=DragonFly
3279 compat.linux.osrelease=4.3-STABLE
3286 ## Tuning with sysctl
3288 [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).
3290 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.
3292 To view all readable variables:
3298 To read a particular variable, for example, `kern.maxproc`:
3302 % sysctl kern.maxproc
3306 To set a particular variable, use the intuitive `***variable***`=`***value***` syntax:
3310 # sysctl kern.maxfiles=5000
3312 kern.maxfiles: 2088 -< 5000
3314 Settings of sysctl variables are usually either strings, numbers, or booleans (a boolean being `1` for yes or a `0` for no).
3316 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].
3318 ### sysctl(8) Read-only
3320 ***Contributed by Tom Rhodes. ***
3322 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.
3324 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:
3328 cbb0: Could not map register memory
3330 device_probe_and_attach: cbb0 attach returned 12
3332 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.
3334 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.
3338 ### Sysctl Variables
3340 #### `vfs.vmiodirenable`
3342 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.
3344 #### `vfs.write_behind`
3346 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.
3348 #### `vfs.hirunningspace`
3350 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.
3352 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.
3354 #### `vm.swap_idle_enabled`
3356 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.
3360 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.
3362 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.
3364 For more information, please see [ata(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=ata§ion=4) manual page.
3366 <!-- XXX: add some more sysctls, e.g. relating to AHCI, nata, ... -->
3370 **Note** that soft updates are only available on UFS.
3372 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:
3376 # tunefs -n enable /filesystem
3378 # tunefs -n disable /filesystem
3380 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.
3382 **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).
3384 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.
3386 #### More Details about Soft Updates
3387 <!-- XXX: consider axing this section -->
3389 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.)
3391 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`).
3393 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.
3395 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.
3397 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.
3399 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.
3401 ## Tuning Kernel Limits
3403 ### File/Process Limits
3405 #### `kern.maxfiles`
3407 <!-- XXX: revise this section; someone who knows about it -->
3409 `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.
3411 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.
3413 `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.
3415 **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.
3417 #### `kern.ipc.somaxconn`
3419 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.
3423 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.
3425 <!-- XXX: mention kern.ipc.mbufs sysctl -->
3427 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.
3429 **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.
3431 #### `net.inet.ip.portrange.*`
3433 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.
3435 #### TCP Bandwidth Delay Product
3436 <!-- XXX: Revise this stuff, I'm not familiar with it -->
3438 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.
3440 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).
3442 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.
3444 ## Adding Swap Space
3445 <!-- XXX: swapcache -->
3447 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.
3449 ### Swap on a New Hard Drive
3451 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.
3453 ### Swapping over NFS
3455 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.
3459 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.
3461 **Example 6-1. Creating a Swapfile**
3463 1. Be certain that your kernel configuration includes the vnode driver. It is ***not*** in recent versions of `GENERIC`.
3467 pseudo-device vn 1 #Vnode driver (turns a file into a device)
3471 1. Create a swapfile (`/usr/swap0`):
3475 # dd if=/dev/zero of=/usr/swap0 bs=1024k count=64
3479 1. Set proper permissions on (`/usr/swap0`):
3483 # chmod 0600 /usr/swap0
3487 1. Enable the swap file in `/etc/rc.conf`:
3491 swapfile="/usr/swap0" # Set to name of swapfile if aux swapfile desired.
3495 1. Reboot the machine or to enable the swap file immediately, type:
3499 # vnconfig -e /dev/vn0b /usr/swap0 swap
3503 ## Power and Resource Management
3505 ***Written by Hiten Pandya and Tom Rhodes. ***
3507 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.
3509 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.
3513 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).
3515 ### Shortcomings of Advanced Power Management (APM)
3517 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.
3519 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.
3521 ***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.
3523 The DragonFly APM driver is documented in the [apm(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=apm§ion=4) manual page.
3525 ### Configuring ACPI
3527 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.
3529 **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.
3531 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:
3537 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.
3539 ## Using and Debugging DragonFly ACPI
3541 ***Written by Nate Lawson. With contributions from Peter Schultz and Tom Rhodes. ***
3543 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.
3545 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.
3547 ### Submitting Debugging Information
3549 **Note:** Before submitting a problem, be sure you are running the latest BIOS version and, if available, embedded controller firmware version.
3551 For those of you that want to submit a problem right away, please send the following information to [bugs](http://leaf.dragonflybsd.org/mailarchive/)
3553 * 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.
3555 * The dmesg output after ***boot `-v`***, including any error messages generated by you exercising the bug.
3557 * dmesg output from ***boot `-v`*** with ACPI disabled, if disabling it helps fix the problem.
3559 * Output from ***sysctl hw.acpi***. This is also a good way of figuring out what features your system offers.
3561 * 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:
3564 # acpidump -t -d > name-system.asl
3568 (Substitute your login name for `name` and manufacturer/model for `system`. Example: `njl-FooCo6000.asl`)
3572 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.
3574 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.
3576 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`.
3580 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.
3584 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.
3586 Start by checking `sysctl` `hw.acpi` for the suspend-related items. Here are the results for my Thinkpad:
3588 hw.acpi.supported_sleep_state: S3 S4 S5
3592 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.
3594 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.
3596 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.
3598 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.
3600 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.
3602 <-- XXX: mention sensors somewhere; but not in this section -->
3604 #### System Hangs (temporary or permanent)
3606 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).
3608 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`.
3610 Your best hope when dealing with interrupt problems is to try disabling APIC support with `hint.apic.0.disabled="1"` in `loader.conf`.
3614 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.
3616 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.
3618 #### System Powers Up After Suspend or Shutdown
3620 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.
3624 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.
3626 ### ASL, acpidump, and IASL
3627 <!-- XXX: IMHO all this crap about fixing your DSDT etc should be axed -->
3629 The most common problem is the BIOS vendors providing incorrect (or outright buggy!) bytecode. This is usually manifested by kernel console messages like this:
3633 ACPI-1287: *** Error: Method execution failed [\\_SB_.PCI0.LPC0.FIGD._STA] \\
3635 (Node 0xc3f6d160), AE_NOT_FOUND
3637 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.
3639 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:
3647 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.
3649 Here is a list of common error messages, their cause, and how to fix them:
3651 #### OS dependencies
3653 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.
3655 #### Missing Return statements
3657 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.
3659 #### Overriding the Default AML
3661 After you customize `your.asl`, you will want to compile it, run:
3666 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.
3668 `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:
3672 acpi_dsdt_load="YES"
3674 acpi_dsdt_name="/boot/DSDT.aml"
3676 Be sure to copy your `DSDT.aml` to the `/boot` directory.
3678 ### Getting Debugging Output From ACPI
3680 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.
3682 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:
3686 # cd /sys/dev/acpica5 && make clean && make ACPI_DEBUG=1
3688 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.
3692 debug.acpi.layer="ACPI_ALL_COMPONENTS ACPI_ALL_DRIVERS"
3694 debug.acpi.level="ACPI_LV_ERROR"
3696 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`.
3700 More information about ACPI may be found in the following locations:
3702 * 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.)
3704 * The ACPI Mailing List Archives (FreeBSD) http://lists.freebsd.org/pipermail/freebsd-acpi/
3706 * The old ACPI Mailing List Archives (FreeBSD) http://home.jp.FreeBSD.org/mail-list/acpi-jp/
3708 * The ACPI 2.0 Specification http://acpi.info/spec.htm
3710 * 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)
3712 * [DSDT debugging resource](http://www.cpqlinux.com/acpi-howto.html#fix_broken_dsdt). (Uses Compaq as an example but generally useful.)
3714 # The DragonFly virtual kernels
3717 ***Obtained from [vkernel(7)](http://leaf.dragonflybsd.org/cgi/web-man?command=vkernel§ion=7) written by Sascha Wildner, added by Matthias Schmidt***
3719 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.
3721 The vkernel architecture allows for running DragonFly kernels in userland.
3723 ## Supported devices
3725 A number of virtual device drivers exist to supplement the virtual kernel.
3727 <!-- XXX: why do they only support 16 devices? is this really true? -->
3731 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`.
3735 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.
3737 ### Network interface
3739 The vke driver supports up to 16 virtual network interfaces which are
3741 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.
3743 ## Setup a virtual kernel environment
3745 A couple of steps are necessary in order to prepare the system to build and run a virtual kernel.
3747 ### Setting up the filesystem
3749 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`:
3753 % mkdir /home/var.vkernel
3754 % ln -s /home/var.vkernel /var/vkernel
3756 Next, a filesystem image to be used by the virtual kernel has to be created and populated (assuming world has been built previously):
3758 # dd if=/dev/zero of=/var/vkernel/rootimg.01 bs=1m count=2048
3759 # vnconfig -c vn0 /var/vkernel/rootimg.01
3760 # disklabel -r -w vn0s0 auto
3761 # disklabel -e vn0s0 # add 'a' partition with fstype `4.2BSD' size could be '*'
3763 # mount /dev/vn0s0a /mnt
3765 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.
3767 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).
3770 # make installworld DESTDIR=/mnt
3772 # make distribution DESTDIR=/mnt
3774 Create a fstab file to let the vkernel find your image file.
3778 # echo '/dev/vkd0s0a / ufs rw 1 1' >/mnt/etc/fstab
3779 # echo 'proc /proc procfs rw 0 0' >>/mnt/etc/fstab
3781 Edit `/mnt/etc/ttys` and replace the console entry with the following line and turn off all other gettys.
3783 # console "/usr/libexec/getty Pc" cons25 on secure
3785 Then, unmount the disk.
3790 ### Compiling the virtual kernel
3792 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):
3796 # make -DNO_MODULES buildkernel KERNCONF=VKERNEL
3797 # make -DNO_MODULES installkernel KERNCONF=VKERNEL DESTDIR=/var/vkernel
3799 ### Enabling virtual kernel operation
3801 A special sysctl(8), `vm.vkernel_enable`, must be set to enable vkernel operation:
3803 # sysctl vm.vkernel_enable=1
3805 To make this change permanent, edit `/etc/sysctl.conf`
3809 ### Configuring the network on the host system
3811 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:
3815 # kldload if_bridge.ko
3817 # ifconfig bridge0 create
3818 # ifconfig bridge0 addm re0 # assuming re0 is the host's interface
3819 # ifconfig bridge0 up
3821 **Note** : You have to change `re0` to the interface of your host machine.
3826 ## Run a virtual kernel
3828 Finally, the virtual kernel can be run:
3831 # ./boot/kernel/kernel -m 64m -r /var/vkernel/rootimg.01 -I auto:bridge0
3833 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.
3835 # The DragonFly Booting Process
3840 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.
3842 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.
3844 After reading this chapter, you will know:
3846 * What the components of the DragonFly bootstrap system are, and how they interact.
3848 * The options you can give to the components in the DragonFly bootstrap to control the boot process.
3850 * The basics of [device.hints(5)](http://leaf.dragonflybsd.org/cgi/web-man?command#device.hints§ion5&manpath=FreeBSD+5.2-current).
3852 **x86 Only:** This chapter only describes the boot process for DragonFly running on x86 systems.
3854 ## The Booting Problem
3856 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?
3858 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***.
3860 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.
3862 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.)
3864 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`.
3866 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.
3868 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.
3870 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.
3874 ## The Boot Manager and Boot Stages
3876 ### The Boot Manager
3878 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** .
3880 **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:
3882 **Example 7-1. `boot0` Screenshot**
3900 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:
3904 # fdisk -B -b /boot/boot0 device
3906 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).
3908 **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:
3916 loader=/boot/chain.b
3920 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.
3922 ### Stage One, /boot/boot1, and Stage Two, /boot/boot2
3924 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).
3926 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`.
3928 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.
3930 `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`.
3932 `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.
3934 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.
3936 **Example 7-2. boot2 Screenshot**
3940 >> DragonFly/i386 BOOT
3942 Default: 0:ad(0,a)/boot/loader
3946 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):
3950 # disklabel -B diskslice
3952 where `***diskslice***` is the disk and slice you boot from, such as `ad0s1` for the first slice on the first IDE disk.
3954 ### Stage Three, `/boot/loader`
3956 The loader is the final stage of the three-stage bootstrap, and is located on the file system, usually as `/boot/loader`.
3958 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.
3960 #### Loader Program Flow
3962 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.
3964 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.
3966 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.
3968 #### Loader Built-In Commands
3970 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).
3972 * 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.
3974 * boot [`***-options***`] [`***kernelname***`]: Immediately proceeds to boot the kernel, with the given options, if any, and with the kernel name given, if it is.
3976 *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`.
3978 * help [`***topic***`]: Shows help messages read from `/boot/loader.help`. If the topic given is `index`, then the list of available topics is given.
3980 * 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.
3982 * 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.
3984 * 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.
3986 * lsdev [`-v`]: Lists all of the devices from which it may be possible to load modules. If `-v` is specified, more details are printed.
3988 * lsmod [`-v`]: Displays loaded modules. If `-v` is specified, more details are shown.
3990 * more `***filename***`: Displays the files specified, with a pause at each `LINES` displayed.
3992 * reboot: Immediately reboots the system.
3994 * set `***variable***`, set `***variable***`=`***value***`: Sets the loader's environment variables.
3996 * unload: Removes all loaded modules.
3998 #### Loader Examples
4000 Here are some practical examples of loader usage:
4002 * To simply boot your usual kernel, but in single-user mode:
4010 * To unload your usual kernel and modules, and then load just your old (or another) kernel:
4020 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).
4022 **Note:** Use the following to load your usual modules with another kernel:
4028 set kernel="kernel.old"
4034 * To load a kernel configuration script (an automated script which does the things you would normally do in the kernel boot-time configurator):
4038 load -t userconfig_script /boot/kernel.conf
4044 ## Kernel Interaction During Boot
4046 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.
4048 ### Kernel Boot Flags
4050 Here are the more common boot flags:
4052 `-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
4054 **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.
4056 ## Init: Process Control Initialization
4058 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`.
4060 ### Automatic Reboot Sequence
4062 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.
4064 ### Single-User Mode
4066 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`.
4068 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).
4070 If the system `console` is set to `insecure` in `/etc/ttys`, then the system prompts for the `root` password before initiating single-user mode.
4072 ***'Example 7-3. An Insecure Console in `/etc/ttys`***'
4076 # name getty type status comments
4080 # If console is marked "insecure", then init will ask for the root password
4082 # when going to single-user mode.
4084 console none unknown off insecure
4086 **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`.
4090 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.
4092 #### Resource Configuration (rc)
4094 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.
4096 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.
4098 ## Shutdown Sequence
4100 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.
4102 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.
4104 **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.
4106 <!-- this section needs the info about sernos and vfs.mountrootfrom or whatever it's called -->
4108 # Users and Basic Account Management
4110 ***Contributed by Neil Blakey-Milner. ***
4116 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.
4118 After reading this chapter, you will know:
4120 * The differences between the various user accounts on a DragonFly system.
4122 * How to add user accounts.
4124 * How to remove user accounts.
4126 * How to change account details, such as the user's full name, or preferred shell.
4128 * 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.
4130 * How to use groups to make account management easier.
4132 Before reading this chapter, you should:
4134 * Understand the basics of UNIX® and DragonFly ([Chapter 3](basics.html)).
4138 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.
4140 Every account on a DragonFly system has certain information associated with it to identify the account.
4142 * 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.
4144 * 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.
4146 * 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.
4148 * Login class: Login classes are an extension to the group mechanism that provide additional flexibility when tailoring the system to different users.
4150 * 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.
4152 * 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.
4154 * 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.
4156 * 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.
4158 * 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.
4160 There are three main types of accounts: the Superuser, system users and 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.
4162 ## The Superuser Account
4164 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.
4166 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.
4168 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.
4170 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.
4174 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.
4176 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.
4178 `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.
4182 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.
4184 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.
4186 Each user can set up their own environment to accommodate their use of the system, by using alternate shells, editors, key bindings, and language.
4188 ## Modifying Accounts
4190 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.
4194 [adduser(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=adduser§ion=8) | The recommended command-line application for adding new users.
4195 [rmuser(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rmuser§ion=8) | The recommended command-line application for removing users.
4196 [chpass(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=chpass§ion=1) | A flexible tool to change user database information.
4197 [passwd(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=passwd§ion=1) | The simple command-line tool to change user passwords.
4198 [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. |
4204 [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.
4206 To create the initial configuration file, use `adduser -s -config_create`. 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.
4208 **Example 8-1. Configuring `adduser` and adding a user**
4214 Use option -silent if you don't want to see all warnings and questions.
4218 Check /etc/master.passwd
4222 Enter your default shell: csh date no sh tcsh zsh [sh]: zsh
4224 Your default shell is: zsh -> /usr/local/bin/zsh
4226 Enter your default HOME partition: [/home]:
4228 Copy dotfiles from: /usr/share/skel no [/usr/share/skel]:
4230 Send message from file: /etc/adduser.message no
4232 [/etc/adduser.message]: no
4236 Use passwords (y/n) [y]: y
4240 Write your changes to /etc/adduser.conf? (y/n) [n]: y
4246 Don't worry about mistakes. I will give you the chance later to correct any input.
4248 Enter username [a-z0-9_-]: jru
4250 Enter full name []: J. Random User
4252 Enter shell csh date no sh tcsh zsh [zsh]:
4254 Enter home directory (full path) [/home/jru]:
4258 Enter login class: default []:
4260 Login group jru [jru]:
4262 Login group is ***jru***. Invite jru into other groups: guest no
4268 Enter password again []:
4276 Fullname: J. Random User
4288 Shell: /usr/local/bin/zsh
4292 Added user ***jru***
4294 Copy files from /usr/share/skel to /home/jru
4296 Add another user? (y/n) [y]: n
4302 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.)
4304 **Note:** The password you type in is not echoed, nor are asterisks displayed. Make sure you do not mistype the password twice.
4306 **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.
4310 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:
4312 1. Removes the user's [crontab(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=crontab§ion=1) entry (if any).
4314 1. Removes any [at(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=at§ion=1) jobs belonging to the user.
4316 1. Kills all processes owned by the user.
4318 1. Removes the user from the system's local password file.
4320 1. Removes the user's home directory (if it is owned by the user).
4322 1. Removes the incoming mail files belonging to the user from `/var/mail`.
4324 1. Removes all files owned by the user from temporary file storage areas such as `/tmp`.
4326 1. Finally, removes the username from all groups to which it belongs in `/etc/group`.
4328 **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).
4330 [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.
4332 By default, an interactive mode is used, which attempts to make sure you know what you are doing.
4334 **Example 8-2. `rmuser` Interactive Account Removal**
4340 Matching password entry:
4342 jru:*:1001:1001::0:0:J. Random User:/home/jru:/usr/local/bin/zsh
4344 Is this the entry you wish to remove? y
4346 Remove user's home directory (/home/jru)? y
4348 Updating password file, updating databases, done.
4350 Updating group file: trusted (removing group jru -- personal group is empty) done.
4352 Removing user's incoming mail file /var/mail/jru: done.
4354 Removing files belonging to jru from /tmp: done.
4356 Removing files belonging to jru from /var/tmp: done.
4358 Removing files belonging to jru from /var/tmp/vi.recover: done.
4364 [chpass(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=chpass§ion=1) changes user database information such as passwords, shells, and personal information.
4366 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).
4368 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.
4370 ***'Example 8-3. Interactive `chpass` by Superuser***'
4374 #Changing user database information for jru.
4382 Gid [# or name]: 1001
4384 Change [month day year]:
4386 Expire [month day year]:
4390 Home directory: /home/jru
4392 Shell: /usr/local/bin/zsh
4394 Full Name: J. Random User
4404 The normal user can change only a small subset of this information, and only for themselves.
4406 **Example 8-4. Interactive chpass by Normal User**
4410 #Changing user database information for jru.
4412 Shell: /usr/local/bin/zsh
4414 Full Name: J. Random User
4424 **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].
4428 [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.
4430 **Note:** To prevent accidental or unauthorized changes, the original password must be entered before a new password can be set.
4432 **Example 8-5. Changing Your Password**
4438 Changing local password for jru.
4444 Retype new password:
4446 passwd: updating the database...
4450 ***'Example 8-6. Changing Another User's Password as the Superuser***'
4456 Changing local password for jru.
4460 Retype new password:
4462 passwd: updating the database...
4466 **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.
4470 [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.
4475 <tablestyle#"width:100%"> 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. |
4481 <!-- XXX: check this section, I got the feeling there might be something outdated in it. I'm not familiar with it -->
4483 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.
4485 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].
4487 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.
4489 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).
4491 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).
4493 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)).
4495 * `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.
4497 * `cputime`: This is the maximum amount of CPU time a user's process may consume. Offending processes will be killed by the kernel.
4499 **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.
4501 * `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.
4503 * `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).
4505 * `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.
4507 * `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.
4509 * `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).
4511 * `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.
4513 * `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.
4515 There are a few other things to remember when setting resource limits. Following are some general tips, suggestions, and miscellaneous comments.
4517 * Processes started at system startup by `/etc/rc` are assigned to the `daemon` login class.
4519 * 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.
4521 * 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.
4523 * 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.
4525 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).
4527 ## Personalizing Users
4529 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).
4533 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.
4535 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.
4537 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:
4539 **Example 8-7. Adding a Group Using pw(8)**
4543 # pw groupadd teamtwo
4545 # pw groupshow teamtwo
4549 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.
4551 **Example 8-8. Adding Somebody to a Group Using pw(8)**
4555 # pw groupmod teamtwo -M jru
4557 # pw groupshow teamtwo
4561 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`.
4563 **Example 8-9. Using id(1) to Determine Group Membership**
4569 uid#1001(jru) gid1001(jru) groups=1001(jru), 1100(teamtwo)
4571 As you can see, `jru` is a member of the groups `jru` and `teamtwo`.
4573 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.
4575 # Configuring the DragonFly Kernel
4577 ***Updated and restructured by Jim Mock. Originally contributed by Jake Hamby.***
4583 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.
4585 After reading this chapter, you will know:
4587 * Why you might need to build a custom kernel.
4588 * How to write a kernel configuration file, or alter an existing configuration file.
4589 * How to use the kernel configuration file to create and build a new kernel.
4590 * How to install the new kernel.
4591 * How to troubleshoot if things go wrong.
4593 ## Why Build a Custom Kernel?
4595 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.
4597 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.
4599 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.
4601 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:
4603 * 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.
4605 * 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.
4607 * 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.
4609 ## Building and Installing a Custom Kernel
4611 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.
4613 ### Installing the Source
4615 If there is ***no*** `/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.
4617 The preferred way of installing the sources is:
4622 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:
4626 ### Your Custom Config File
4628 Next, move to the `config` directory and copy the `GENERIC` configuration file to the name you want to give your kernel. For example:
4630 # cd /usr/src/sys/config
4631 # cp GENERIC MYKERNEL
4633 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.
4635 **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.
4639 # cd /usr/src/sys/config
4640 # mkdir /root/kernels
4641 # cp GENERIC /root/kernels/MYKERNEL
4642 # ln -s /root/kernels/MYKERNEL
4644 **Note:** You must execute these and all of the following commands under the `root` account or you will get permission denied errors.
4646 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`.
4648 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.
4650 ### Building a Kernel - Full Source Tree
4652 **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.
4654 1. Change to the `/usr/src` directory.
4660 1. Compile the kernel.
4662 # make buildkernel KERNCONF=MYKERNEL
4664 1. Install the new kernel.
4666 # make installkernel KERNCONF=MYKERNEL
4670 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.
4672 ### Building a Kernel - Kernel Source Only
4674 When only the kernel source is installed, you need to change step 2, above, to this:
4677 # make nativekernel KERNCONF=MYKERNEL
4679 The other steps are the same.
4681 ### Running Your New Kernel
4683 The installer copies the new kernel and modules to `/boot/kernel/`, the kernel being `/boot/kernel/kernel` and the modules being `/boot/kernel/*.ko`. The old kernel and modules are moved to `/boot/kernel.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).
4685 **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.
4687 ## The Configuration File
4688 <!-- XXX: do we really want to mention all these million config options? -->
4689 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`.
4691 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`.
4699 # GENERIC -- Generic kernel configuration file for DragonFly/i386
4703 # Check the LINT configuration file in sys/config, for an
4705 # exhaustive list of options.
4709 # $DragonFly: src/sys/config/GENERIC,v 1.56 2007/12/26 14:02:36 sephe Exp $
4711 The following are the mandatory keywords required in ***every*** kernel you build:
4717 This is the machine architecture. It must be `i386` at the moment. Support for `amd64` will be added in the future.
4729 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.
4735 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).
4741 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.
4743 (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.
4745 **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`].
4749 # Floating point support - do not disable.
4751 device npx0 at nexus? port IO_NPX irq 13
4753 `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.
4757 # Pseudo devices - the number indicates how many units to allocate.
4759 pseudo-device loop # Network loopback
4761 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***.
4763 Everything that follows is more or less optional. See the notes underneath or next to each option for more information.
4767 #makeoptions DEBUG=-g #Build kernel with gdb(1) debug symbols
4769 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).
4773 options MATH_EMULATE #Support for x87 emulation
4775 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.
4777 **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.
4781 options INET #InterNETworking
4783 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.
4787 options INET6 #IPv6 communications protocols
4789 This enables the IPv6 communication protocols.
4793 options FFS #Berkeley Fast Filesystem
4795 options FFS_ROOT #FFS usable as root device [keep this!]
4797 This is the basic hard drive Filesystem. Leave it in if you boot from the hard disk.
4801 options UFS_DIRHASH #Improve performance on big directories
4803 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.
4807 options SOFTUPDATES #Enable FFS Soft Updates support
4809 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.
4813 options MFS #Memory Filesystem
4815 options MD_ROOT #MD is a potential root device
4817 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`:
4821 /dev/ad1s2b /tmp mfs rw 0 0
4823 Now you simply need to either reboot, or run the command `mount /tmp`.
4827 options NFS #Network Filesystem
4829 options NFS_ROOT #NFS usable as root device, NFS required
4831 The network Filesystem. Unless you plan to mount partitions from a UNIX® file server over TCP/IP, you can comment these out.
4835 options MSDOSFS #MSDOS Filesystem
4837 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).
4841 options CD9660 #ISO 9660 Filesystem
4843 options CD9660_ROOT #CD-ROM usable as root, CD9660 required
4845 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.
4849 options PROCFS #Process filesystem
4851 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. ***
4855 Compatibility with 4.3BSD. Leave this in; some programs will act strangely if you comment this out.
4859 options SCSI_DELAY=5000 #Delay (in ms) before probing SCSI
4861 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.
4865 options UCONSOLE #Allow users to grab the console
4867 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.
4871 options USERCONFIG #boot -c editor
4873 This option allows you to boot the configuration editor from the boot menu.
4877 options VISUAL_USERCONFIG #visual boot -c editor
4879 This option allows you to boot the visual configuration editor from the boot menu.
4883 options KTRACE #ktrace(1) support
4885 This enables kernel process tracing, which is useful in debugging.
4889 options SYSVSHM #SYSV-style shared memory
4891 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.
4895 options SYSVSEM #SYSV-style semaphores
4897 Support for System V semaphores. Less commonly used but only adds a few hundred bytes to the kernel.
4901 options SYSVMSG #SYSV-style message queues
4903 Support for System V messages. Again, only adds a few hundred bytes to the kernel.
4905 **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.
4909 options P1003_1B #Posix P1003_1B real-time extensions
4911 options _KPOSIX_PRIORITY_SCHEDULING
4913 Real-time extensions added in the 1993 POSIX®. Certain applications in the ports collection use these (such as **StarOffice™** ).
4917 options ICMP_BANDLIM #Rate limit bad replies
4919 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.
4923 # To make an SMP kernel, the next two are needed
4925 #options SMP # Symmetric MultiProcessor Kernel
4927 #options APIC_IO # Symmetric (APIC) I/O
4929 The above are both required for SMP support.
4935 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`.
4941 Include this if you have an EISA motherboard. This enables auto-detection and configuration support for all devices on the EISA bus.
4947 Include this if you have a PCI motherboard. This enables auto-detection of PCI cards and gatewaying from the PCI to ISA bus.
4953 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.
4959 device fdc0 at isa? port IO_FD1 irq 6 drq 2
4961 device fd0 at fdc0 drive 0
4963 device fd1 at fdc0 drive 1
4965 This is the floppy drive controller. `fd0` is the `A:` floppy drive, and `fd1` is the `B:` drive.
4971 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.
4975 device atadisk # ATA disk drives
4977 This is needed along with `device ata` for ATA disk drives.
4981 device atapicd # ATAPI CDROM drives
4983 This is needed along with `device ata` for ATAPI CDROM drives.
4987 device atapifd # ATAPI floppy drives
4989 This is needed along with `device ata` for ATAPI floppy drives.
4993 device atapist # ATAPI tape drives
4995 This is needed along with `device ata` for ATAPI tape drives.
4999 options ATA_STATIC_ID #Static device numbering
5001 This makes the controller number static (like the old driver) or else the device numbers are dynamically allocated.
5005 # ATA and ATAPI devices
5007 device ata0 at isa? port IO_WD1 irq 14
5009 device ata1 at isa? port IO_WD2 irq 15
5011 Use the above for older, non-PCI systems.
5017 device ahb # EISA AHA1742 family
5019 device ahc # AHA2940 and onboard AIC7xxx devices
5021 device amd # AMD 53C974 (Teckram DC-390(T))
5023 device dpt # DPT Smartcache - See LINT for options!
5025 device isp # Qlogic family
5027 device ncr # NCR/Symbios Logic
5029 device sym # NCR/Symbios Logic (newer chipsets)
5041 SCSI controllers. Comment out any you do not have in your system. If you have an IDE only system, you can remove these altogether.
5047 device scbus # SCSI bus (required)
5049 device da # Direct Access (disks)
5051 device sa # Sequential Access (tape etc)
5055 device pass # Passthrough device (direct SCSI
5059 SCSI peripherals. Again, comment out any you do not have, or if you have only IDE hardware, you can remove them completely.
5061 **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.
5067 device ida # Compaq Smart RAID
5069 device amr # AMI MegaRAID
5071 device mlx # Mylex DAC960 family
5073 Supported RAID controllers. If you do not have any of these, you can comment them out or remove them.
5077 # atkbdc0 controls both the keyboard and the PS/2 mouse
5079 device atkbdc0 at isa? port IO_KBD
5081 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`).
5085 device atkbd0 at atkbdc? irq 1
5087 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.
5091 device psm0 at atkbdc? irq 12
5093 Use this device if your mouse plugs into the PS/2 mouse port.
5099 The video card driver.
5103 # splash screen/screen saver
5105 pseudo-device splash
5107 Splash screen at start up! Screen savers require this too.
5111 # syscons is the default console driver, resembling an SCO console
5115 `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.
5119 # Enable this and PCVT_FREEBSD for pcvt vt220 compatible console driver
5123 #options XSERVER # support for X server on a vt console
5125 #options FAT_CURSOR # start with block cursor
5127 # If you have a ThinkPAD, uncomment this along with the rest of the PCVT lines
5129 #options PCVT_SCANSET=2 # IBM keyboards are non-std
5131 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.
5135 # Power management support (see LINT for more options)
5137 device apm0 at nexus? disable flags 0x20 # Advanced Power Management
5139 Advanced Power Management support. Useful for laptops.
5143 # PCCARD (PCMCIA) support
5147 device pcic0 at isa? irq 10 port 0x3e0 iomem 0xd0000
5149 device pcic1 at isa? irq 11 port 0x3e2 iomem 0xd4000 disable
5151 PCMCIA support. You want this if you are using a laptop.
5155 # Serial (COM) ports
5157 device sio0 at isa? port IO_COM1 flags 0x10 irq 4
5159 device sio1 at isa? port IO_COM2 irq 3
5161 device sio2 at isa? disable port IO_COM3 irq 5
5163 device sio3 at isa? disable port IO_COM4 irq 9
5165 These are the four serial ports referred to as COM1 through COM4 in the MS-DOS/Windows® world.
5167 **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.
5169 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.
5175 device ppc0 at isa? irq 7
5177 This is the ISA-bus parallel port interface.
5181 device ppbus # Parallel port bus (required)
5183 Provides support for the parallel port bus.
5187 device lpt # Printer
5189 Support for parallel port printers.
5191 **Note:** All three of the above are required to enable parallel printer support.
5195 device plip # TCP/IP over parallel
5197 This is the driver for the parallel network interface.
5201 device ppi # Parallel port interface device
5203 The general-purpose I/O (***geek port) + IEEE1284 I/O.
5207 #device vpo # Requires scbus and da
5209 This is for an Iomega Zip drive. It requires `scbus` and `da` support. Best performance is achieved with ports in EPP 1.9 mode.
5213 # PCI Ethernet NICs.
5215 device de # DEC/Intel DC21x4x (Tulip)
5217 device fxp # Intel EtherExpress PRO/100B (82557, 82558)
5219 device tx # SMC 9432TX (83c170 EPIC)
5221 device vx # 3Com 3c590, 3c595 (Vortex)
5223 device wx # Intel Gigabit Ethernet Card (Wiseman)
5225 Various PCI network card drivers. Comment out or remove any of these not present in your system.
5229 # PCI Ethernet NICs that use the common MII bus controller code.
5231 device miibus # MII bus support
5233 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.
5237 device dc # DEC/Intel 21143 and various workalikes
5239 device rl # RealTek 8129/8139
5241 device sf # Adaptec AIC-6915 (Starfire)
5243 device sis # Silicon Integrated Systems SiS 900/SiS 7016
5245 device ste # Sundance ST201 (D-Link DFE-550TX)
5247 device tl # Texas Instruments ThunderLAN
5249 device vr # VIA Rhine, Rhine II
5251 device wb # Winbond W89C840F
5253 device xl # 3Com 3c90x (Boomerang, Cyclone)
5255 Drivers that use the MII bus controller code.
5259 # ISA Ethernet NICs.
5261 device ed0 at isa? port 0x280 irq 10 iomem 0xd8000
5267 # WaveLAN/IEEE 802.11 wireless NICs. Note: the WaveLAN/IEEE really
5269 # exists only as a PCMCIA device, so there is no ISA attachment needed
5271 # and resources will always be dynamically assigned by the pccard code.
5275 # Aironet 4500/4800 802.11 wireless NICs. Note: the declaration below will
5277 # work for PCMCIA and PCI cards, as well as ISA cards set to ISA PnP
5279 # mode (the factory default). If you set the switches on your ISA
5281 # card for a manually chosen I/O address and IRQ, you must specify
5283 # those parameters here.
5287 # The probe order of these is presently determined by i386/isa/isa_compat.c.
5289 device ie0 at isa? port 0x300 irq 10 iomem 0xd0000
5291 device fe0 at isa? port 0x300
5293 device le0 at isa? port 0x300 irq 5 iomem 0xd0000
5295 device lnc0 at isa? port 0x280 irq 10 drq 0
5297 device cs0 at isa? port 0x300
5299 device sn0 at isa? port 0x300 irq 10
5301 # requires PCCARD (PCMCIA) support to be activated
5305 ISA Ethernet drivers. See `/usr/src/sys/config/LINT` for which cards are supported by which driver.
5309 pseudo-device ether # Ethernet support
5311 `ether` is only needed if you have an Ethernet card. It includes generic Ethernet protocol code.
5315 pseudo-device sl 1 # Kernel SLIP
5317 `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.
5321 pseudo-device ppp 1 # Kernel PPP
5323 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. .
5327 device tun # Packet tunnel.
5329 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.
5333 pseudo-device pty # Pseudo-ttys (telnet etc)
5335 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. ***
5339 Memory disk pseudo-devices.
5343 pseudo-device gif # IPv6 and IPv4 tunneling
5345 This implements IPv6 over IPv4 tunneling, IPv4 over IPv6 tunneling, IPv4 over IPv4 tunneling, and IPv6 over IPv6 tunneling.
5349 pseudo-device faith # IPv6-to-IPv4 relaying (translation)
5351 This pseudo-device captures packets that are sent to it and diverts them to the IPv4/IPv6 translation daemon.
5355 # The `bpf' device enables the Berkeley Packet Filter.
5357 # Be aware of the administrative consequences of enabling this!
5359 pseudo-device bpf # Berkeley packet filter
5361 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.
5363 **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.
5369 #device uhci # UHCI PCI->USB interface
5371 #device ohci # OHCI PCI->USB interface
5373 #device usb # USB Bus (required)
5375 #device ugen # Generic
5377 #device uhid # ***Human Interface Devices***
5379 #device ukbd # Keyboard
5381 #device ulpt # Printer
5383 #device umass # Disks/Mass storage - Requires scbus and da
5387 # USB Ethernet, requires mii
5389 #device aue # ADMtek USB ethernet
5391 #device cue # CATC USB ethernet
5393 #device kue # Kawasaki LSI USB ethernet
5395 Support for various USB devices.
5397 For more information and additional devices supported by DragonFly, see `/usr/src/sys/i386/conf/LINT`.
5402 <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. |
5408 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.
5410 These nodes are created automatically once devfs is mounted, which happens manually for the root `/dev` during boot, just after the root mount.
5412 ## If Something Goes Wrong
5414 **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:
5416 % chflags noschg /boot/kernel
5419 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.
5421 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:
5425 % chflags schg /boot/kernel
5428 There are five categories of trouble that can occur when building a custom kernel. They are:
5430 * `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.
5432 * `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.
5434 * 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.
5436 * 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.
5438 * 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.
5441 ***Much of this chapter has been taken from the security(7) manual page by Matthew Dillon. ***
5447 This chapter will provide a basic introduction to system security concepts, some general good rules of thumb, and some advanced topics under DragonFly. A lot of the topics covered here can be applied to system and Internet security in general as well. The Internet is no longer a ***friendly*** place in which everyone wants to be your kind neighbor. Securing your system is imperative to protect your data, intellectual property, time, and much more from the hands of hackers and the like.
5449 DragonFly provides an array of utilities and mechanisms to ensure the integrity and security of your system and network.
5451 After reading this chapter, you will know:
5453 * Basic system security concepts, in respect to DragonFly.
5455 * About the various crypt mechanisms available in DragonFly, such as DES and MD5.
5457 * How to set up one-time password authentication.
5459 * How to create firewalls using IPFW.
5461 * How to configure IPsec and create a VPN between DragonFly/Windows® machines.
5463 * How to configure and use **OpenSSH** , DragonFly's SSH implementation.
5465 Before reading this chapter, you should:
5467 * Understand basic DragonFly and Internet concepts.
5475 Security is a function that begins and ends with the system administrator. While all BSD UNIX® multi-user systems have some inherent security, the job of building and maintaining additional security mechanisms to keep those users ***honest*** is probably one of the single largest undertakings of the sysadmin. Machines are only as secure as you make them, and security concerns are ever competing with the human necessity for convenience. UNIX systems, in general, are capable of running a huge number of simultaneous processes and many of these processes operate as servers -- meaning that external entities can connect and talk to them. As yesterday's mini-computers and mainframes become today's desktops, and as computers become networked and internetworked, security becomes an even bigger issue.
5477 Security is best implemented through a layered ***onion*** approach. In a nutshell, what you want to do is to create as many layers of security as are convenient and then carefully monitor the system for intrusions. You do not want to overbuild your security or you will interfere with the detection side, and detection is one of the single most important aspects of any security mechanism. For example, it makes little sense to set the `schg` flags (see [chflags(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#chflags§ion1)) on every system binary because while this may temporarily protect the binaries, it prevents an attacker who has broken in from making an easily detectable change that may result in your security mechanisms not detecting the attacker at all.
5479 System security also pertains to dealing with various forms of attack, including attacks that attempt to crash, or otherwise make a system unusable, but do not attempt to compromise the `root` account (***break root***). Security concerns can be split up into several categories:
5481 1. Denial of service attacks.
5483 1. User account compromises.
5485 1. Root compromise through accessible servers.
5487 1. Root compromise via user accounts.
5489 1. Backdoor creation.
5491 A denial of service attack is an action that deprives the machine of needed resources. Typically, DoS attacks are brute-force mechanisms that attempt to crash or otherwise make a machine unusable by overwhelming its servers or network stack. Some DoS attacks try to take advantage of bugs in the networking stack to crash a machine with a single packet. The latter can only be fixed by applying a bug fix to the kernel. Attacks on servers can often be fixed by properly specifying options to limit the load the servers incur on the system under adverse conditions. Brute-force network attacks are harder to deal with. A spoofed-packet attack, for example, is nearly impossible to stop, short of cutting your system off from the Internet. It may not be able to take your machine down, but it can saturate your Internet connection.
5493 A user account compromise is even more common than a DoS attack. Many sysadmins still run standard **telnetd** , **rlogind** , **rshd** , and **ftpd** servers on their machines. These servers, by default, do not operate over encrypted connections. The result is that if you have any moderate-sized user base, one or more of your users logging into your system from a remote location (which is the most common and convenient way to login to a system) will have his or her password sniffed. The attentive system admin will analyze his remote access logs looking for suspicious source addresses even for successful logins.
5495 One must always assume that once an attacker has access to a user account, the attacker can break `root`. However, the reality is that in a well secured and maintained system, access to a user account does not necessarily give the attacker access to `root`. The distinction is important because without access to `root` the attacker cannot generally hide his tracks and may, at best, be able to do nothing more than mess with the user's files, or crash the machine. User account compromises are very common because users tend not to take the precautions that sysadmins take.
5497 System administrators must keep in mind that there are potentially many ways to break `root` on a machine. The attacker may know the `root` password, the attacker may find a bug in a root-run server and be able to break `root` over a network connection to that server, or the attacker may know of a bug in a suid-root program that allows the attacker to break `root` once he has broken into a user's account. If an attacker has found a way to break `root` on a machine, the attacker may not have a need to install a backdoor. Many of the `root` holes found and closed to date involve a considerable amount of work by the attacker to cleanup after himself, so most attackers install backdoors. A backdoor provides the attacker with a way to easily regain `root` access to the system, but it also gives the smart system administrator a convenient way to detect the intrusion. Making it impossible for an attacker to install a backdoor may actually be detrimental to your security, because it will not close off the hole the attacker found to break in the first place.
5499 Security remedies should always be implemented with a multi-layered ***onion peel*** approach and can be categorized as follows:
5501 1. Securing `root` and staff accounts.
5503 1. Securing `root` -- root-run servers and suid/sgid binaries.
5505 1. Securing user accounts.
5507 1. Securing the password file.
5509 1. Securing the kernel core, raw devices, and filesystems.
5511 1. Quick detection of inappropriate changes made to the system.
5515 The next section of this chapter will cover the above bullet items in greater depth.
5519 CategoryHandbook-security
5521 ## Securing DragonFly
5523 **Command vs. Protocol:** Throughout this document, we will use **bold** text to refer to a command or application. This is used for instances such as ssh, since it is a protocol as well as command.
5525 The sections that follow will cover the methods of securing your DragonFly system that were mentioned in the [last section](security-intro.html) of this chapter.
5527 ### Securing the root Account and Staff Accounts
5529 First off, do not bother securing staff accounts if you have not secured the `root` account. Most systems have a password assigned to the `root` account. The first thing you do is assume that the password is ***always*** compromised. This does not mean that you should remove the password. The password is almost always necessary for console access to the machine. What it does mean is that you should not make it possible to use the password outside of the console or possibly even with the [su(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#su§ion1) command. For example, make sure that your pty's are specified as being insecure in the `/etc/ttys` file so that direct `root` logins via `telnet` or `rlogin` are disallowed. If using other login services such as **sshd** , make sure that direct `root` logins are disabled there as well. You can do this by editing your `/etc/ssh/sshd_config` file, and making sure that `PermitRootLogin` is set to `NO`. Consider every access method -- services such as FTP often fall through the cracks. Direct `root` logins should only be allowed via the system console.
5531 Of course, as a sysadmin you have to be able to get to `root`, so we open up a few holes. But we make sure these holes require additional password verification to operate. One way to make `root` accessible is to add appropriate staff accounts to the `wheel` group (in `/etc/group`). The staff members placed in the `wheel` group are allowed to `su` to `root`. You should never give staff members native `wheel` access by putting them in the `wheel` group in their password entry. Staff accounts should be placed in a `staff` group, and then added to the `wheel` group via the `/etc/group` file. Only those staff members who actually need to have `root` access should be placed in the `wheel` group. While having the `wheel` mechanism is better than having nothing at all, it is not necessarily the safest option.
5533 An indirect way to secure staff accounts, and ultimately `root` access is to use an alternative login access method and do what is known as ***starring*** out the encrypted password for the staff accounts. Using the [vipw(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#vipw§ion8) command, one can replace each instance of an encrypted password with a single `*` character. This command will update the `/etc/master.passwd` file and user/password database to disable password-authenticated logins.
5535 A staff account entry such as:
5539 foobar:R9DT/Fa1/LV9U:1000:1000::0:0:Foo Bar:/home/foobar:/usr/local/bin/tcsh
5541 Should be changed to this:
5545 foobar:*:1000:1000::0:0:Foo Bar:/home/foobar:/usr/local/bin/tcsh
5547 This change will prevent normal logins from occurring, since the encrypted password will never match `*`. With this done, staff members must use another mechanism to authenticate themselves such as [ssh(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ssh§ion=1&manpath=OpenBSD+3.3) using a public/private key pair. When using a public/private key pair with ssh, one must generally secure the machine used to login ***from*** (typically one's workstation). An additional layer of protection can be added to the key pair by password protecting the key pair when creating it with [ssh-keygen(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ssh-keygen§ion=1). Being able to ***star*** out the passwords for staff accounts also guarantees that staff members can only login through secure access methods that you have set up. This forces all staff members to use secure, encrypted connections for all of their sessions, which closes an important hole used by many intruders: sniffing the network from an unrelated, less secure machine.
5549 The more indirect security mechanisms also assume that you are logging in from a more restrictive server to a less restrictive server. For example, if your main box is running all sorts of servers, your workstation should not be running any. In order for your workstation to be reasonably secure you should run as few servers as possible, up to and including no servers at all, and you should run a password-protected screen blanker. Of course, given physical access to a workstation an attacker can break any sort of security you put on it. This is definitely a problem that you should consider, but you should also consider the fact that the vast majority of break-ins occur remotely, over a network, from people who do not have physical access to your workstation or servers.
5551 ### Securing Root-run Servers and SUID/SGID Binaries
5553 The prudent sysadmin only runs the servers he needs to, no more, no less. Be aware that third party servers are often the most bug-prone. For example, running an old version of **imapd** or **popper** is like giving a universal `root` ticket out to the entire world. Never run a server that you have not checked out carefully. Many servers do not need to be run as `root`. For example, the **ntalk** , **comsat** , and **finger** daemons can be run in special user ***sandboxes***. A sandbox is not perfect, unless you go through a large amount of trouble, but the onion approach to security still stands: If someone is able to break in through a server running in a sandbox, they still have to break out of the sandbox. The more layers the attacker must break through, the lower the likelihood of his success. Root holes have historically been found in virtually every server ever run as `root`, including basic system servers. If you are running a machine through which people only login via **sshd** and never login via **telnetd** or **rshd** or **rlogind** , then turn off those services!
5555 DragonFly now defaults to running **ntalkd** , **comsat** , and **finger** in a sandbox. Another program which may be a candidate for running in a sandbox is [named(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#named§ion8). `/etc/defaults/rc.conf` includes the arguments necessary to run **named** in a sandbox in a commented-out form. Depending on whether you are installing a new system or upgrading an existing system, the special user accounts used by these sandboxes may not be installed. The prudent sysadmin would research and implement sandboxes for servers whenever possible.
5557 There are a number of other servers that typically do not run in sandboxes: **sendmail** , **popper** , **imapd** , **ftpd** , and others. There are alternatives to some of these, but installing them may require more work than you are willing to perform (the convenience factor strikes again). You may have to run these servers as `root` and rely on other mechanisms to detect break-ins that might occur through them.
5559 The other big potential `root` holes in a system are the suid-root and sgid binaries installed on the system. Most of these binaries, such as **rlogin** , reside in `/bin`, `/sbin`, `/usr/bin`, or `/usr/sbin`. While nothing is 100% safe, the system-default suid and sgid binaries can be considered reasonably safe. Still, `root` holes are occasionally found in these binaries. A `root` hole was found in `Xlib` in 1998 that made **xterm** (which is typically suid) vulnerable. It is better to be safe than sorry and the prudent sysadmin will restrict suid binaries, that only staff should run, to a special group that only staff can access, and get rid of (`chmod 000`) any suid binaries that nobody uses. A server with no display generally does not need an **xterm** binary. Sgid binaries can be almost as dangerous. If an intruder can break an sgid-kmem binary, the intruder might be able to read `/dev/kmem` and thus read the encrypted password file, potentially compromising any passworded account. Alternatively an intruder who breaks group `kmem` can monitor keystrokes sent through pty's, including pty's used by users who login through secure methods. An intruder that breaks the `tty` group can write to almost any user's tty. If a user is running a terminal program or emulator with a keyboard-simulation feature, the intruder can potentially generate a data stream that causes the user's terminal to echo a command, which is then run as that user.
5561 ### Securing User Accounts
5563 User accounts are usually the most difficult to secure. While you can impose Draconian access restrictions on your staff and ***star*** out their passwords, you may not be able to do so with any general user accounts you might have. If you do have sufficient control, then you may win out and be able to secure the user accounts properly. If not, you simply have to be more vigilant in your monitoring of those accounts. Use of ssh for user accounts is more problematic, due to the extra administration and technical support required, but still a very good solution compared to a crypted password file.
5565 ### Securing the Password File
5567 The only sure fire way is to `*` out as many passwords as you can and use ssh for access to those accounts. Even though the encrypted password file (`/etc/spwd.db`) can only be read by `root`, it may be possible for an intruder to obtain read access to that file even if the attacker cannot obtain root-write access.
5569 Your security scripts should always check for and report changes to the password file (see the [Checking file integrity](securing-freebsd.html#SECURITY-INTEGRITY) section below).
5571 ### Securing the Kernel Core, Raw Devices, and Filesystems
5573 If an attacker breaks `root` he can do just about anything, but there are certain conveniences. For example, most modern kernels have a packet sniffing device driver built in. Under DragonFly it is called the `bpf` device. An intruder will commonly attempt to run a packet sniffer on a compromised machine. You do not need to give the intruder the capability and most systems do not have the need for the `bpf` device compiled in.
5575 But even if you turn off the `bpf` device, you still have `/dev/mem` and `/dev/kmem` to worry about. For that matter, the intruder can still write to raw disk devices. Also, there is another kernel feature called the module loader, [kldload(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#kldload§ion8). An enterprising intruder can use a KLD module to install his own `bpf` device, or other sniffing device, on a running kernel. To avoid these problems you have to run the kernel at a higher secure level, at least securelevel 1. The securelevel can be set with a `sysctl` on the `kern.securelevel` variable. Once you have set the securelevel to 1, write access to raw devices will be denied and special `chflags` flags, such as `schg`, will be enforced. You must also ensure that the `schg` flag is set on critical startup binaries, directories, and script files -- everything that gets run up to the point where the securelevel is set. This might be overdoing it, and upgrading the system is much more difficult when you operate at a higher secure level. You may compromise and run the system at a higher secure level but not set the `schg` flag for every system file and directory under the sun. Another possibility is to simply mount `/` and `/usr` read-only. It should be noted that being too Draconian in what you attempt to protect may prevent the all-important detection of an intrusion.
5577 ### Checking File Integrity: Binaries, Configuration Files, Etc.
5579 When it comes right down to it, you can only protect your core system configuration and control files so much before the convenience factor rears its ugly head. For example, using `chflags` to set the `schg` bit on most of the files in `/` and `/usr` is probably counterproductive, because while it may protect the files, it also closes a detection window. The last layer of your security onion is perhaps the most important -- detection. The rest of your security is pretty much useless (or, worse, presents you with a false sense of safety) if you cannot detect potential incursions. Half the job of the onion is to slow down the attacker, rather than stop him, in order to give the detection side of the equation a chance to catch him in the act.
5581 The best way to detect an incursion is to look for modified, missing, or unexpected files. The best way to look for modified files is from another (often centralized) limited-access system. Writing your security scripts on the extra-secure limited-access system makes them mostly invisible to potential attackers, and this is important. In order to take maximum advantage you generally have to give the limited-access box significant access to the other machines in the business, usually either by doing a read-only NFS export of the other machines to the limited-access box, or by setting up ssh key-pairs to allow the limited-access box to ssh to the other machines. Except for its network traffic, NFS is the least visible method -- allowing you to monitor the filesystems on each client box virtually undetected. If your limited-access server is connected to the client boxes through a switch, the NFS method is often the better choice. If your limited-access server is connected to the client boxes through a hub, or through several layers of routing, the NFS method may be too insecure (network-wise) and using ssh may be the better choice even with the audit-trail tracks that ssh lays.
5583 Once you give a limited-access box, at least read access to the client systems it is supposed to monitor, you must write scripts to do the actual monitoring. Given an NFS mount, you can write scripts out of simple system utilities such as [find(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#find§ion1) and [md5(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=md5§ion=1). It is best to physically md5 the client-box files at least once a day, and to test control files such as those found in `/etc` and `/usr/local/etc` even more often. When mismatches are found, relative to the base md5 information the limited-access machine knows is valid, it should scream at a sysadmin to go check it out. A good security script will also check for inappropriate suid binaries and for new or deleted files on system partitions such as `/` and `/usr`.
5585 When using ssh rather than NFS, writing the security script is much more difficult. You essentially have to `scp` the scripts to the client box in order to run them, making them visible, and for safety you also need to `scp` the binaries (such as find) that those scripts use. The **ssh** client on the client box may already be compromised. All in all, using ssh may be necessary when running over insecure links, but it is also a lot harder to deal with.
5587 A good security script will also check for changes to user and staff members access configuration files: `.rhosts`, `.shosts`, `.ssh/authorized_keys` and so forth... files that might fall outside the purview of the `MD5` check.
5589 If you have a huge amount of user disk space, it may take too long to run through every file on those partitions. In this case, setting mount flags to disallow suid binaries and devices on those partitions is a good idea. The `nodev` and `nosuid` options (see [mount(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#mount§ion8)) are what you want to look into. You should probably scan them anyway, at least once a week, since the object of this layer is to detect a break-in whether or not the break-in is effective.
5591 Process accounting (see [accton(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#accton§ion8)) is a relatively low-overhead feature of the operating system which might help as a post-break-in evaluation mechanism. It is especially useful in tracking down how an intruder has actually broken into a system, assuming the file is still intact after the break-in occurs.
5593 Finally, security scripts should process the log files, and the logs themselves should be generated in as secure a manner as possible -- remote syslog can be very useful. An intruder tries to cover his tracks, and log files are critical to the sysadmin trying to track down the time and method of the initial break-in. One way to keep a permanent record of the log files is to run the system console to a serial port and collect the information on a continuing basis through a secure machine monitoring the consoles.
5597 A little paranoia never hurts. As a rule, a sysadmin can add any number of security features, as long as they do not affect convenience, and can add security features that ***do*** affect convenience with some added thought. Even more importantly, a security administrator should mix it up a bit -- if you use recommendations such as those given by this document verbatim, you give away your methodologies to the prospective attacker who also has access to this document.
5599 ### Denial of Service Attacks
5601 This section covers Denial of Service attacks. A DoS attack is typically a packet attack. While there is not much you can do about modern spoofed packet attacks that saturate your network, you can generally limit the damage by ensuring that the attacks cannot take down your servers.
5603 1. Limiting server forks.
5605 1. Limiting springboard attacks (ICMP response attacks, ping broadcast, etc.).
5607 1. Kernel Route Cache.
5609 A common DoS attack is against a forking server that attempts to cause the server to eat processes, file descriptors, and memory, until the machine dies. **inetd** (see [inetd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#inetd§ion8)) has several options to limit this sort of attack. It should be noted that while it is possible to prevent a machine from going down, it is not generally possible to prevent a service from being disrupted by the attack. Read the **inetd** manual page carefully and pay specific attention to the `-c`, `-C`, and `-R` options. Note that spoofed-IP attacks will circumvent the `-C` option to **inetd** , so typically a combination of options must be used. Some standalone servers have self-fork-limitation parameters.
5611 **Sendmail** has its `-OMaxDaemonChildren` option, which tends to work much better than trying to use sendmail's load limiting options due to the load lag. You should specify a `MaxDaemonChildren` parameter, when you start **sendmail** , high enough to handle your expected load, but not so high that the computer cannot handle that number of **sendmails** without falling on its face. It is also prudent to run sendmail in queued mode (`-ODeliveryMode=queued`) and to run the daemon (`sendmail -bd`) separate from the queue-runs (`sendmail -q15m`). If you still want real-time delivery you can run the queue at a much lower interval, such as `-q1m`, but be sure to specify a reasonable `MaxDaemonChildren` option for ***that*** sendmail to prevent cascade failures.
5613 **Syslogd** can be attacked directly and it is strongly recommended that you use the `-s` option whenever possible, and the `-a` option otherwise.
5615 You should also be fairly careful with connect-back services such as **tcpwrapper** s reverse-identd, which can be attacked directly. You generally do not want to use the reverse-ident feature of **tcpwrappers** for this reason.
5617 It is a very good idea to protect internal services from external access by firewalling them off at your border routers. The idea here is to prevent saturation attacks from outside your LAN, not so much to protect internal services from network-based `root` compromise. Always configure an exclusive firewall, i.e., firewall everything ***except*** ports A, B, C, D, and M-Z. This way you can firewall off all of your low ports except for certain specific services such as **named** (if you are primary for a zone), **ntalkd** , **sendmail** , and other Internet-accessible services. If you try to configure the firewall the other way -- as an inclusive or permissive firewall, there is a good chance that you will forget to ***close*** a couple of services, or that you will add a new internal service and forget to update the firewall. You can still open up the high-numbered port range on the firewall, to allow permissive-like operation, without compromising your low ports. Also take note that DragonFly allows you to control the range of port numbers used for dynamic binding, via the various `net.inet.ip.portrange` `sysctl`'s (`sysctl -a | fgrep portrange`), which can also ease the complexity of your firewall's configuration. For example, you might use a normal first/last range of 4000 to 5000, and a hiport range of 49152 to 65535, then block off everything under 4000 in your firewall (except for certain specific Internet-accessible ports, of course).
5619 Another common DoS attack is called a springboard attack -- to attack a server in a manner that causes the server to generate responses which overloads the server, the local network, or some other machine. The most common attack of this nature is the ***ICMP ping broadcast attack***. The attacker spoofs ping packets sent to your LAN's broadcast address with the source IP address set to the actual machine they wish to attack. If your border routers are not configured to stomp on ping's to broadcast addresses, your LAN winds up generating sufficient responses to the spoofed source address to saturate the victim, especially when the attacker uses the same trick on several dozen broadcast addresses over several dozen different networks at once. Broadcast attacks of over a hundred and twenty megabits have been measured. A second common springboard attack is against the ICMP error reporting system. By constructing packets that generate ICMP error responses, an attacker can saturate a server's incoming network and cause the server to saturate its outgoing network with ICMP responses. This type of attack can also crash the server by running it out of mbuf's, especially if the server cannot drain the ICMP responses it generates fast enough. The DragonFly kernel has a new kernel compile option called `ICMP_BANDLIM` which limits the effectiveness of these sorts of attacks. The last major class of springboard attacks is related to certain internal **inetd** services such as the udp echo service. An attacker simply spoofs a UDP packet with the source address being server A's echo port, and the destination address being server B's echo port, where server A and B are both on your LAN. The two servers then bounce this one packet back and forth between each other. The attacker can overload both servers and their LANs simply by injecting a few packets in this manner. Similar problems exist with the internal **chargen** port. A competent sysadmin will turn off all of these inetd-internal test services.
5621 Spoofed packet attacks may also be used to overload the kernel route cache. Refer to the `net.inet.ip.rtexpire`, `rtminexpire`, and `rtmaxcache` `sysctl` parameters. A spoofed packet attack that uses a random source IP will cause the kernel to generate a temporary cached route in the route table, viewable with `netstat -rna | fgrep W3`. These routes typically timeout in 1600 seconds or so. If the kernel detects that the cached route table has gotten too big it will dynamically reduce the `rtexpire` but will never decrease it to less than `rtminexpire`. There are two problems:
5623 1. The kernel does not react quickly enough when a lightly loaded server is suddenly attacked.
5625 1. The `rtminexpire` is not low enough for the kernel to survive a sustained attack.
5627 If your servers are connected to the Internet via a T3 or better, it may be prudent to manually override both `rtexpire` and `rtminexpire` via [sysctl(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#sysctl§ion8). Never set either parameter to zero (unless you want to crash the machine). Setting both parameters to two seconds should be sufficient to protect the route table from attack.
5629 ## DES, MD5, and Crypt
5631 ***Parts rewritten and updated by Bill Swingle. ***
5633 Every user on a UNIX® system has a password associated with their account. It seems obvious that these passwords need to be known only to the user and the actual operating system. In order to keep these passwords secret, they are encrypted with what is known as a ***one-way hash***, that is, they can only be easily encrypted but not decrypted. In other words, what we told you a moment ago was obvious is not even true: the operating system itself does not ***really*** know the password. It only knows the ***encrypted*** form of the password. The only way to get the ***plain-text*** password is by a brute force search of the space of possible passwords.
5635 Unfortunately the only secure way to encrypt passwords when UNIX came into being was based on DES, the Data Encryption Standard. This was not such a problem for users resident in the US, but since the source code for DES could not be exported outside the US, DragonFly had to find a way to both comply with US law and retain compatibility with all the other UNIX variants that still used DES.
5637 The solution was to divide up the encryption libraries so that US users could install the DES libraries and use DES but international users still had an encryption method that could be exported abroad. This is how DragonFly came to use MD5 as its default encryption method. MD5 is believed to be more secure than DES, so installing DES is offered primarily for compatibility reasons.
5639 ### Recognizing Your Crypt Mechanism
5641 `libcrypt.a` provides a configurable password authentication hash library. Currently the library supports DES, MD5, Blowfish, SHA256, and SHA512 hash functions. By default DragonFly uses SHA256 to encrypt passwords.
5643 It is pretty easy to identify which encryption method DragonFly is set up to use. Examining the encrypted passwords in the `/etc/master.passwd` file is one way. Passwords encrypted with the MD5 hash are longer than those encrypted with the DES hash and also begin with the characters `$1$`. Passwords starting with `$2a$` are encrypted with the Blowfish hash function. DES password strings do not have any particular identifying characteristics, but they are shorter than MD5 passwords, and are coded in a 64-character alphabet which does not include the `$` character, so a relatively short string which does not begin with a dollar sign is very likely a DES password.
5645 The password format used for new passwords is controlled by the `passwd_format` login capability in `/etc/login.conf`, which takes values of `des`, `md5` or `blf`. See the [login.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command#login.conf&section5) manual page for more information about login capabilities.
5647 ## One-time Passwords
5649 S/Key is a one-time password scheme based on a one-way hash function. DragonFly uses the MD4 hash for compatibility but other systems have used MD5 and DES-MAC. S/Key ia part of the FreeBSD base system, and is also used on a growing number of other operating systems. S/Key is a registered trademark of Bell Communications Research, Inc.
5651 There are three different sorts of passwords which we will discuss below. The first is your usual UNIX® style password; we will call this a ***UNIX password***. The second sort is the one-time password which is generated by the S/Key `key` program or the OPIE [opiekey(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#opiekey§ion1) program and accepted by the `keyinit` or [opiepasswd(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=opiepasswd§ion=1) programs and the login prompt; we will call this a ***one-time password***. The final sort of password is the secret password which you give to the `key`/`opiekey` programs (and sometimes the `keyinit`/`opiepasswd` programs) which it uses to generate one-time passwords; we will call it a ***secret password*** or just unqualified ***password***.
5653 The secret password does not have anything to do with your UNIX password; they can be the same but this is not recommended. S/Key and OPIE secret passwords are not limited to eight characters like old UNIX passwords[(1)](#FTN.AEN8429), they can be as long as you like. Passwords of six or seven word long phrases are fairly common. For the most part, the S/Key or OPIE system operates completely independently of the UNIX password system.
5655 Besides the password, there are two other pieces of data that are important to S/Key and OPIE. One is what is known as the ***seed*** or ***key***, consisting of two letters and five digits. The other is what is called the ***iteration count***, a number between 1 and 100. S/Key creates the one-time password by concatenating the seed and the secret password, then applying the MD4/MD5 hash as many times as specified by the iteration count and turning the result into six short English words. These six English words are your one-time password. The authentication system (primarily PAM) keeps track of the last one-time password used, and the user is authenticated if the hash of the user-provided password is equal to the previous password. Because a one-way hash is used it is impossible to generate future one-time passwords if a successfully used password is captured; the iteration count is decremented after each successful login to keep the user and the login program in sync. When the iteration count gets down to 1, S/Key and OPIE must be reinitialized.
5657 There are three programs involved in each system which we will discuss below. The `key` and `opiekey` programs accept an iteration count, a seed, and a secret password, and generate a one-time password or a consecutive list of one-time passwords. The `keyinit` and `opiepasswd` programs are used to initialize S/Key and OPIE respectively, and to change passwords, iteration counts, or seeds; they take either a secret passphrase, or an iteration count, seed, and one-time password. The `keyinfo` and `opieinfo` programs examine the relevant credentials files (`/etc/skeykeys` or `/etc/opiekeys`) and print out the invoking user's current iteration count and seed.
5659 There are four different sorts of operations we will cover. The first is using `keyinit` or `opiepasswd` over a secure connection to set up one-time-passwords for the first time, or to change your password or seed. The second operation is using `keyinit` or `opiepasswd` over an insecure connection, in conjunction with `key` or `opiekey` over a secure connection, to do the same. The third is using `key`/`opiekey` to log in over an insecure connection. The fourth is using `key` or `opiekey` to generate a number of keys which can be written down or printed out to carry with you when going to some location without secure connections to anywhere.
5661 ### Secure Connection Initialization
5663 To initialize S/Key for the first time, change your password, or change your seed while logged in over a secure connection (e.g., on the console of a machine or via **ssh** ), use the `keyinit` command without any parameters while logged in as yourself:
5671 Reminder - Only use this method if you are directly connected.
5673 If you are using telnet or rlogin exit with no password and use keyinit -s.
5675 Enter secret password:
5677 Again secret password:
5681 ID unfurl s/key is 99 to17757
5683 DEFY CLUB PRO NASH LACE SOFT
5685 For OPIE, `opiepasswd` is used instead:
5691 [grimreaper] ~ $ opiepasswd -f -c
5695 Only use this method from the console; NEVER from remote. If you are using
5697 telnet, xterm, or a dial-in, type ^C now or exit with no password.
5699 Then run opiepasswd without the -c parameter.
5701 Using MD5 to compute responses.
5703 Enter new secret pass phrase:
5705 Again new secret pass phrase:
5707 ID unfurl OTP key is 499 to4268
5709 MOS MALL GOAT ARM AVID COED
5711 At the Enter new secret pass phrase: or Enter secret password: prompts, you should enter a password or phrase. Remember, this is not the password that you will use to login with, this is used to generate your one-time login keys. The ***ID*** line gives the parameters of your particular instance: your login name, the iteration count, and seed. When logging in the system will remember these parameters and present them back to you so you do not have to remember them. The last line gives the particular one-time password which corresponds to those parameters and your secret password; if you were to re-login immediately, this one-time password is the one you would use.
5713 ### Insecure Connection Initialization
5715 To initialize or change your secret password over an insecure connection, you will need to already have a secure connection to some place where you can run `key` or `opiekey`; this might be in the form of a desk accessory on a Macintosh®, or a shell prompt on a machine you trust. You will also need to make up an iteration count (100 is probably a good value), and you may make up your own seed or use a randomly-generated one. Over on the insecure connection (to the machine you are initializing), use the `keyinit -s` command:
5725 Reminder you need the 6 English words from the key command.
5727 Enter sequence count from 1 to 9999: 100
5729 Enter new key [default to17759]:
5733 s/key access password:
5735 s/key access password:CURE MIKE BANE HIM RACY GORE
5737 For OPIE, you need to use `opiepasswd`:
5747 You need the response from an OTP generator.
5749 Old secret pass phrase:
5751 otp-md5 498 to4268 ext
5753 Response: GAME GAG WELT OUT DOWN CHAT
5755 New secret pass phrase:
5759 Response: LINE PAP MILK NELL BUOY TROY
5763 ID mark OTP key is 499 gr4269
5765 LINE PAP MILK NELL BUOY TROY
5767 To accept the default seed (which the `keyinit` program confusingly calls a `key`), press **Return** . Then before entering an access password, move over to your secure connection or S/Key desk accessory, and give it the same parameters:
5773 Reminder - Do not use this program while logged in via telnet or rlogin.
5775 Enter secret password: <secret password>
5777 CURE MIKE BANE HIM RACY GORE
5783 % opiekey 498 to4268
5785 Using the MD5 algorithm to compute response.
5787 Reminder: Don't use opiekey from telnet or dial-in sessions.
5789 Enter secret pass phrase:
5791 GAME GAG WELT OUT DOWN CHAT
5793 Now switch back over to the insecure connection, and copy the one-time password generated over to the relevant program.
5795 ### Generating a Single One-time Password
5797 Once you have initialized S/Key, when you login you will be presented with a prompt like this:
5801 % telnet example.com
5805 Connected to example.com
5807 Escape character is '^]'.
5811 DragonFly/i386 (example.com) (ttypa)
5815 login: <username>
5825 % telnet example.com
5829 Connected to example.com
5831 Escape character is '^]'.
5835 DragonFly/i386 (example.com) (ttypa)
5839 login: <username>
5841 otp-md5 498 gr4269 ext
5845 As a side note, the S/Key and OPIE prompts have a useful feature (not shown here): if you press **Return** at the password prompt, the prompter will turn echo on, so you can see what you are typing. This can be extremely useful if you are attempting to type in a password by hand, such as from a printout.
5847 At this point you need to generate your one-time password to answer this login prompt. This must be done on a trusted system that you can run `key` or `opiekey` on. (There are versions of these for DOS, Windows® and Mac OS® as well.) They need both the iteration count and the seed as command line options. You can cut-and-paste these right from the login prompt on the machine that you are logging in to.
5849 On the trusted system:
5855 Reminder - Do not use this program while logged in via telnet or rlogin.
5857 Enter secret password:
5859 WELD LIP ACTS ENDS ME HAAG
5865 % opiekey 498 to4268
5867 Using the MD5 algorithm to compute response.
5869 Reminder: Don't use opiekey from telnet or dial-in sessions.
5871 Enter secret pass phrase:
5873 GAME GAG WELT OUT DOWN CHAT
5875 Now that you have your one-time password you can continue logging in:
5879 login: <username>
5883 Password: <return to enable echo>
5887 Password [echo on]: WELD LIP ACTS ENDS ME HAAG
5889 Last login: Tue Mar 21 11:56:41 from 10.0.0.2 ...
5891 ### Generating Multiple One-time Passwords
5893 Sometimes you have to go places where you do not have access to a trusted machine or secure connection. In this case, it is possible to use the `key` and `opiekey` commands to generate a number of one-time passwords beforehand to be printed out and taken with you. For example:
5897 % key -n 5 30 zz99999
5899 Reminder - Do not use this program while logged in via telnet or rlogin.
5901 Enter secret password: <secret password>
5903 26: SODA RUDE LEA LIND BUDD SILT
5905 27: JILT SPY DUTY GLOW COWL ROT
5907 28: THEM OW COLA RUNT BONG SCOT
5909 29: COT MASH BARR BRIM NAN FLAG
5911 30: CAN KNEE CAST NAME FOLK BILK
5917 % opiekey -n 5 30 zz99999
5919 Using the MD5 algorithm to compute response.
5921 Reminder: Don't use opiekey from telnet or dial-in sessions.
5923 Enter secret pass phrase: <secret password>
5925 26: JOAN BORE FOSS DES NAY QUIT
5927 27: LATE BIAS SLAY FOLK MUCH TRIG
5929 28: SALT TIN ANTI LOON NEAL USE
5931 29: RIO ODIN GO BYE FURY TIC
5933 30: GREW JIVE SAN GIRD BOIL PHI
5935 The `-n 5` requests five keys in sequence, the `30` specifies what the last iteration number should be. Note that these are printed out in ***reverse*** order of eventual use. If you are really paranoid, you might want to write the results down by hand; otherwise you can cut-and-paste into `lpr`. Note that each line shows both the iteration count and the one-time password; you may still find it handy to scratch off passwords as you use them.
5937 ### Restricting Use of UNIX® Passwords
5939 S/Key can place restrictions on the use of UNIX passwords based on the host name, user name, terminal port, or IP address of a login session. These restrictions can be found in the configuration file `/etc/skey.access`. The [skey.access(5)](http://leaf.dragonflybsd.org/cgi/web-man?command#skey.access§ion5) manual page has more information on the complete format of the file and also details some security cautions to be aware of before depending on this file for security.
5941 If there is no `/etc/skey.access` file (this is the default), then all users will be allowed to use UNIX passwords. If the file exists, however, then all users will be required to use S/Key unless explicitly permitted to do otherwise by configuration statements in the `skey.access` file. In all cases, UNIX passwords are permitted on the console.
5943 Here is a sample `skey.access` configuration file which illustrates the three most common sorts of configuration statements:
5947 permit internet 192.168.0.0 255.255.0.0
5953 The first line (`permit internet`) allows users whose IP source address (which is vulnerable to spoofing) matches the specified value and mask, to use UNIX passwords. This should not be considered a security mechanism, but rather, a means to remind authorized users that they are using an insecure network and need to use S/Key for authentication.
5955 The second line (`permit user`) allows the specified username, in this case `fnord`, to use UNIX passwords at any time. Generally speaking, this should only be used for people who are either unable to use the `key` program, like those with dumb terminals, or those who are uneducable.
5957 The third line (`permit port`) allows all users logging in on the specified terminal line to use UNIX passwords; this would be used for dial-ups.
5959 Here is a sample `opieaccess` file:
5963 permit 192.168.0.0 255.255.0.0
5965 This line allows users whose IP source address (which is vulnerable to spoofing) matches the specified value and mask, to use UNIX passwords at any time.
5967 If no rules in `opieaccess` are matched, the default is to deny non-OPIE logins.
5972 |<tablestyle="width:100%"> [one-time-passwords.html#AEN8429 (1)] | Under DragonFly the standard login password may be up to 128 characters in length. |
5978 CategoryHandbook-security
5982 ***Contributed by Gary Palmer and Alex Nash. ***
5984 Firewalls are an area of increasing interest for people who are connected to the Internet, and are even finding applications on private networks to provide enhanced security. This section will hopefully explain what firewalls are, how to use them, and how to use the facilities provided in the DragonFly kernel to implement them.
5986 **Note:** People often think that having a firewall between your internal network and the ***Big Bad Internet*** will solve all your security problems. It may help, but a poorly set up firewall system is more of a security risk than not having one at all. A firewall can add another layer of security to your systems, but it cannot stop a really determined cracker from penetrating your internal network. If you let internal security lapse because you believe your firewall to be impenetrable, you have just made the crackers job that much easier.
5988 ### What Is a Firewall?
5990 There are currently two distinct types of firewalls in common use on the Internet today. The first type is more properly called a ***packet filtering router***. This type of firewall utilizes a multi-homed machine and a set of rules to determine whether to forward or block individual packets. A multi-homed machine is simply a device with multiple network interfaces. The second type, known as a ***proxy server***, relies on daemons to provide authentication and to forward packets, possibly on a multi-homed machine which has kernel packet forwarding disabled.
5992 Sometimes sites combine the two types of firewalls, so that only a certain machine (known as a ***bastion host***) is allowed to send packets through a packet filtering router onto an internal network. Proxy services are run on the bastion host, which are generally more secure than normal authentication mechanisms.
5994 DragonFly comes with a kernel packet filter (known as IPFW), which is what the rest of this section will concentrate on. Proxy servers can be built on DragonFly from third party software, but there is such a variety of proxy servers available that it would be impossible to cover them in this section.
5996 #### Packet Filtering Routers
5998 A router is a machine which forwards packets between two or more networks. A packet filtering router is programmed to compare each packet to a list of rules before deciding if it should be forwarded or not. Most modern IP routing software includes packet filtering functionality that defaults to forwarding all packets. To enable the filters, you need to define a set of rules.
6000 To decide whether a packet should be passed on, the firewall looks through its set of rules for a rule which matches the contents of the packet's headers. Once a match is found, the rule action is obeyed. The rule action could be to drop the packet, to forward the packet, or even to send an ICMP message back to the originator. Only the first match counts, as the rules are searched in order. Hence, the list of rules can be referred to as a ***rule chain***.
6002 The packet-matching criteria varies depending on the software used, but typically you can specify rules which depend on the source IP address of the packet, the destination IP address, the source port number, the destination port number (for protocols which support ports), or even the packet type (UDP, TCP, ICMP, etc).
6006 Proxy servers are machines which have had the normal system daemons ( **telnetd** , **ftpd** , etc) replaced with special servers. These servers are called ***proxy servers***, as they normally only allow onward connections to be made. This enables you to run (for example) a proxy **telnet** server on your firewall host, and people can **telnet** in to your firewall from the outside, go through some authentication mechanism, and then gain access to the internal network (alternatively, proxy servers can be used for signals coming from the internal network and heading out).
6008 Proxy servers are normally more secure than normal servers, and often have a wider variety of authentication mechanisms available, including ***one-shot*** password systems so that even if someone manages to discover what password you used, they will not be able to use it to gain access to your systems as the password expires immediately after the first use. As they do not actually give users access to the host machine, it becomes a lot more difficult for someone to install backdoors around your security system.
6010 Proxy servers often have ways of restricting access further, so that only certain hosts can gain access to the servers. Most will also allow the administrator to specify which users can talk to which destination machines. Again, what facilities are available depends largely on what proxy software you choose.
6012 ### Firewall options in DragonFlyBSD
6014 DragonFlyBSD inherited the IPFW firewall (versions 1 and 2) when it forked from FreeBSD. Pretty soon after though, we imported the new pf packet filter that the OpenBSD developers created from scratch. It is a cleaner code base and is now the recommended solution for firewalling DragonFly. Keep in mind that the PF version in DragonFly is not in sync with OpenBSD's PF code. We have not yet incorporated the improvements made in PF over the last few years, but we have some improvements of our own. IPFW is still and will remain supported for the forseeable future; it has some features not yet available in PF.
6016 A copy of the OpenBSD PF user's guide corresponding to the version of PF in DragonFly can be found in [[PFUsersGuide]].
6018 #### What Does IPFW Allow Me to Do?
6020 IPFW, the software supplied with DragonFly, is a packet filtering and accounting system which resides in the kernel, and has a user-land control utility, [ipfw(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#ipfw§ion8). Together, they allow you to define and query the rules used by the kernel in its routing decisions.
6022 There are two related parts to IPFW. The firewall section performs packet filtering. There is also an IP accounting section which tracks usage of the router, based on rules similar to those used in the firewall section. This allows the administrator to monitor how much traffic the router is getting from a certain machine, or how much WWW traffic it is forwarding, for example.
6024 As a result of the way that IPFW is designed, you can use IPFW on non-router machines to perform packet filtering on incoming and outgoing connections. This is a special case of the more general use of IPFW, and the same commands and techniques should be used in this situation.
6026 #### Enabling IPFW on DragonFly
6028 As the main part of the IPFW system lives in the kernel, you will need to add one or more options to your kernel configuration file, depending on what facilities you want, and recompile your kernel. See "Reconfiguring your Kernel" ([kernelconfig.html Chapter 9]) for more details on how to recompile your kernel.
6030 **Warning:** IPFW defaults to a policy of `deny ip from any to any`. If you do not add other rules during startup to allow access, ***you will lock yourself out*** of the server upon rebooting into a firewall-enabled kernel. We suggest that you set `firewall_type=open` in your `/etc/rc.conf` file when first enabling this feature, then refining the firewall rules in `/etc/rc.firewall` after you have tested that the new kernel feature works properly. To be on the safe side, you may wish to consider performing the initial firewall configuration from the local console rather than via **ssh** . Another option is to build a kernel using both the `IPFIREWALL` and `IPFIREWALL_DEFAULT_TO_ACCEPT` options. This will change the default rule of IPFW to `allow ip from any to any` and avoid the possibility of a lockout.
6032 There are currently four kernel configuration options relevant to IPFW:
6034 `options IPFIREWALL`:: Compiles into the kernel the code for packet filtering.`options IPFIREWALL_VERBOSE`:: Enables code to allow logging of packets through [syslogd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#syslogd§ion8). Without this option, even if you specify that packets should be logged in the filter rules, nothing will happen.`options IPFIREWALL_VERBOSE_LIMIT=10`:: Limits the number of packets logged through [syslogd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=syslogd§ion=8) on a per entry basis. You may wish to use this option in hostile environments in which you want to log firewall activity, but do not want to be open to a denial of service attack via syslog flooding.
6036 When a chain entry reaches the packet limit specified, logging is turned off for that particular entry. To resume logging, you will need to reset the associated counter using the [ipfw(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#ipfw§ion8) utility:
6042 Where 4500 is the chain entry you wish to continue logging.`options IPFIREWALL_DEFAULT_TO_ACCEPT`:: This changes the default rule action from ***deny*** to ***allow***. This avoids the possibility of locking yourself out if you happen to boot a kernel with `IPFIREWALL` support but have not configured your firewall yet. It is also very useful if you often use [ipfw(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#ipfw§ion8) as a filter for specific problems as they arise. Use with care though, as this opens up the firewall and changes the way it works.
6044 #### Configuring IPFW
6046 The configuration of the IPFW software is done through the [ipfw(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#ipfw§ion8) utility. The syntax for this command looks quite complicated, but it is relatively simple once you understand its structure.
6048 There are currently four different command categories used by the utility: addition/deletion, listing, flushing, and clearing. Addition/deletion is used to build the rules that control how packets are accepted, rejected, and logged. Listing is used to examine the contents of your rule set (otherwise known as the chain) and packet counters (accounting). Flushing is used to remove all entries from the chain. Clearing is used to zero out one or more accounting entries.
6050 ##### Altering the IPFW Rules
6052 The syntax for this form of the command is:
6054 `ipfw` [-N] command [index] action [log] protocol addresses [options]
6056 There is one valid flag when using this form of the command:
6058 -N:: Resolve addresses and service names in output.
6060 The ***command*** given can be shortened to the shortest unique form. The valid ***commands*** are:
6062 add:: Add an entry to the firewall/accounting rule listdelete:: Delete an entry from the firewall/accounting rule list
6064 Previous versions of IPFW used separate firewall and accounting entries. The present version provides packet accounting with each firewall entry.
6066 If an ***index*** value is supplied, it is used to place the entry at a specific point in the chain. Otherwise, the entry is placed at the end of the chain at an index 100 greater than the last chain entry (this does not include the default policy, rule 65535, deny).
6068 The `log` option causes matching rules to be output to the system console if the kernel was compiled with `IPFIREWALL_VERBOSE`.
6070 Valid ***actions*** are:
6072 reject:: Drop the packet, and send an ICMP host or port unreachable (as appropriate) packet to the source.allow:: Pass the packet on as normal. (aliases: `pass`, `permit`, and `accept`)deny:: Drop the packet. The source is not notified via an ICMP message (thus it appears that the packet never arrived at the destination).count:: Update packet counters but do not allow/deny the packet based on this rule. The search continues with the next chain entry.
6074 Each ***action*** will be recognized by the shortest unambiguous prefix.
6076 The ***protocols*** which can be specified are:
6078 all:: Matches any IP packeticmp:: Matches ICMP packetstcp:: Matches TCP packetsudp:: Matches UDP packets
6080 The ***address*** specification is:
6082 from `***address/mask***` [`***port***`] to `***address/mask***` [`***port***`] [via `***interface***`]
6084 You can only specify `***port***` in conjunction with ***protocols*** which support ports (UDP and TCP).
6086 The `via` is optional and may specify the IP address or domain name of a local IP interface, or an interface name (e.g. `ed0`) to match only packets coming through this interface. Interface unit numbers can be specified with an optional wildcard. For example, `ppp*` would match all kernel PPP interfaces.
6088 The syntax used to specify an `***address/mask***` is:
6098 `***address***`/`***mask-bits***`
6104 `***address***`:`***mask-pattern***`
6106 A valid hostname may be specified in place of the IP address. ' **mask-bits** ' is a decimal number representing how many bits in the address mask should be set. e.g. specifying `192.216.222.1/24` will create a mask which will allow any address in a class C subnet (in this case, `192.216.222`) to be matched. ' **mask-pattern** ' is an IP address which will be logically AND'ed with the address given. The keyword `any` may be used to specify ***any IP address***.
6108 The port numbers to be blocked are specified as:
6110 `***port***` [,`***port***` [,`***port***` [...]]]
6112 to specify either a single port or a list of ports, or
6114 `***port***`-`***port***`
6116 to specify a range of ports. You may also combine a single range with a list, but the range must always be specified first.
6118 The ***options*** available are:
6120 frag:: Matches if the packet is not the first fragment of the datagram.in:: Matches if the packet is on the way in.out:: Matches if the packet is on the way out.ipoptions `***spec***`:: Matches if the IP header contains the comma separated list of options specified in `***spec***`. The supported IP options are: `ssrr` (strict source route), `lsrr` (loose source route), `rr` (record packet route), and `ts` (time stamp). The absence of a particular option may be specified with a leading `!`.established:: Matches if the packet is part of an already established TCP connection (i.e. it has the RST or ACK bits set). You can optimize the performance of the firewall by placing ***established*** rules early in the chain.setup:: Matches if the packet is an attempt to establish a TCP connection (the SYN bit is set but the ACK bit is not).tcpflags `***flags***`:: Matches if the TCP header contains the comma separated list of `***flags***`. The supported flags are `fin`, `syn`, `rst`, `psh`, `ack`, and `urg`. The absence of a particular flag may be indicated by a leading `!`.icmptypes `***types***`:: Matches if the ICMP type is present in the list `***types***`. The list may be specified as any combination of ranges and/or individual types separated by commas. Commonly used ICMP types are: `0` echo reply (ping reply), `3` destination unreachable, `5` redirect, `8` echo request (ping request), and `11` time exceeded (used to indicate TTL expiration as with [traceroute(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#traceroute§ion8)).
6122 ##### Listing the IPFW Rules
6124 The syntax for this form of the command is:
6126 `ipfw` [-a] [-c] [-d] [-e] [-t] [-N] [-S] list
6128 There are seven valid flags when using this form of the command:
6130 -a:: While listing, show counter values. This option is the only way to see accounting counters.-c:: List rules in compact form.-d:: Show dynamic rules in addition to static rules.-e:: If `-d` was specified, also show expired dynamic rules.-t:: Display the last match times for each chain entry. The time listing is incompatible with the input syntax used by the [ipfw(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#ipfw§ion8) utility.-N:: Attempt to resolve given addresses and service names.-S:: Show the set each rule belongs to. If this flag is not specified, disabled rules will not be listed.
6132 ##### Flushing the IPFW Rules
6134 The syntax for flushing the chain is:
6138 This causes all entries in the firewall chain to be removed except the fixed default policy enforced by the kernel (index 65535). Use caution when flushing rules; the default deny policy will leave your system cut off from the network until allow entries are added to the chain.
6140 ##### Clearing the IPFW Packet Counters
6142 The syntax for clearing one or more packet counters is:
6144 `ipfw` zero [`***index***`]
6146 When used without an `***index***` argument, all packet counters are cleared. If an `***index***` is supplied, the clearing operation only affects a specific chain entry.
6148 #### Example Commands for **ipfw**
6150 This command will deny all packets from the host `evil.crackers.org` to the telnet port of the host `nice.people.org`:
6154 # ipfw add deny tcp from evil.crackers.org to nice.people.org 23
6156 The next example denies and logs any TCP traffic from the entire `crackers.org` network (a class C) to the `nice.people.org` machine (any port).
6160 # ipfw add deny log tcp from evil.crackers.org/24 to nice.people.org
6162 If you do not want people sending X sessions to your internal network (a subnet of a class C), the following command will do the necessary filtering:
6166 # ipfw add deny tcp from any to my.org/28 6000 setup
6168 To see the accounting records:
6174 or in the short form
6180 You can also see the last time a chain entry was matched with:
6186 #### Building a Packet Filtering Firewall
6188 **Note:** The following suggestions are just that: suggestions. The requirements of each firewall are different and we cannot tell you how to build a firewall to meet your particular requirements.
6190 When initially setting up your firewall, unless you have a test bench setup where you can configure your firewall host in a controlled environment, it is strongly recommend you use the logging version of the commands and enable logging in the kernel. This will allow you to quickly identify problem areas and cure them without too much disruption. Even after the initial setup phase is complete, I recommend using the logging for `deny' as it allows tracing of possible attacks and also modification of the firewall rules if your requirements alter.
6192 **Note:** If you use the logging versions of the `accept` command, be aware that it can generate ***large*** amounts of log data. One log entry will be generated for every packet that passes through the firewall, so large FTP/http transfers, etc, will really slow the system down. It also increases the latencies on those packets as it requires more work to be done by the kernel before the packet can be passed on. **syslogd** will also start using up a lot more processor time as it logs all the extra data to disk, and it could quite easily fill the partition `/var/log` is located on.
6194 You should enable your firewall from `/etc/rc.conf.local` or `/etc/rc.conf`. The associated manual page explains which knobs to fiddle and lists some preset firewall configurations. If you do not use a preset configuration, `ipfw list` will output the current ruleset into a file that you can pass to `rc.conf`. If you do not use `/etc/rc.conf.local` or `/etc/rc.conf` to enable your firewall, it is important to make sure your firewall is enabled before any IP interfaces are configured.
6196 The next problem is what your firewall should actually ***do***! This is largely dependent on what access to your network you want to allow from the outside, and how much access to the outside world you want to allow from the inside. Some general rules are:
6198 * Block all incoming access to ports below 1024 for TCP. This is where most of the security sensitive services are, like finger, SMTP (mail) and telnet.
6200 * Block ***all*** incoming UDP traffic. There are very few useful services that travel over UDP, and what useful traffic there is, is normally a security threat (e.g. Suns RPC and NFS protocols). This has its disadvantages also, since UDP is a connectionless protocol, denying incoming UDP traffic also blocks the replies to outgoing UDP traffic. This can cause a problem for people (on the inside) using external archie (prospero) servers. If you want to allow access to archie, you will have to allow packets coming from ports 191 and 1525 to any internal UDP port through the firewall. **ntp** is another service you may consider allowing through, which comes from port 123.
6202 * Block traffic to port 6000 from the outside. Port 6000 is the port used for access to X11 servers, and can be a security threat (especially if people are in the habit of doing `xhost +` on their workstations). X11 can actually use a range of ports starting at 6000, the upper limit being how many X displays you can run on the machine. The upper limit as defined by RFC 1700 (Assigned Numbers) is 6063.
6204 * Check what ports any internal servers use (e.g. SQL servers, etc). It is probably a good idea to block those as well, as they normally fall outside the 1-1024 range specified above.
6206 Another checklist for firewall configuration is available from CERT at http://www.cert.org/tech_tips/packet_filtering.html
6208 As stated above, these are only ***guidelines***. You will have to decide what filter rules you want to use on your firewall yourself. We cannot accept ANY responsibility if someone breaks into your network, even if you follow the advice given above.
6210 #### IPFW Overhead and Optimization
6212 Many people want to know how much overhead IPFW adds to a system. The answer to this depends mostly on your rule set and processor speed. For most applications dealing with Ethernet and small rule sets, the answer is ***negligible***. For those of you that need actual measurements to satisfy your curiosity, read on.
6214 The following measurements were made using FreeBSD 2.2.5-STABLE on a 486-66. (While IPFW has changed slightly in later releases of DragonFly, it still performs with similar speed.) IPFW was modified to measure the time spent within the `ip_fw_chk` routine, displaying the results to the console every 1000 packets.
6216 Two rule sets, each with 1000 rules, were tested. The first set was designed to demonstrate a worst case scenario by repeating the rule:
6220 # ipfw add deny tcp from any to any 55555
6222 This demonstrates a worst case scenario by causing most of IPFW's packet check routine to be executed before finally deciding that the packet does not match the rule (by virtue of the port number). Following the 999th iteration of this rule was an `allow ip from any to any`.
6224 The second set of rules were designed to abort the rule check quickly:
6228 # ipfw add deny ip from 1.2.3.4 to 1.2.3.4
6230 The non-matching source IP address for the above rule causes these rules to be skipped very quickly. As before, the 1000th rule was an `allow ip from any to any`.
6232 The per-packet processing overhead in the former case was approximately 2.703 ms/packet, or roughly 2.7 microseconds per rule. Thus the theoretical packet processing limit with these rules is around 370 packets per second. Assuming 10 Mbps Ethernet and a ~1500 byte packet size, we would only be able to achieve 55.5% bandwidth utilization.
6234 For the latter case each packet was processed in approximately 1.172 ms, or roughly 1.2 microseconds per rule. The theoretical packet processing limit here would be about 853 packets per second, which could consume 10 Mbps Ethernet bandwidth.
6236 The excessive number of rules tested and the nature of those rules do not provide a real-world scenario -- they were used only to generate the timing information presented here. Here are a few things to keep in mind when building an efficient rule set:
6238 * Place an `established` rule early on to handle the majority of TCP traffic. Do not put any `allow tcp` statements before this rule.
6240 * Place heavily triggered rules earlier in the rule set than those rarely used (***without changing the permissiveness of the firewall***, of course). You can see which rules are used most often by examining the packet counting statistics with `ipfw -a l`.
6244 CategoryHandbook-security
6248 [OpenSSL](http://www.openssl.org/) provides a general-purpose cryptography library, as well as the Secure Sockets Layer v2/v3 (SSLv2/SSLv3) and Transport Layer Security v1 (TLSv1) network security protocols.
6250 However, one of the algorithms (specifically IDEA) included in OpenSSL is protected by patents in the USA and elsewhere, and is not available for unrestricted use. IDEA is included in the OpenSSL sources in DragonFly, but it is not built by default. If you wish to use it, and you comply with the license terms, enable the `MAKE_IDEA` switch in `/etc/make.conf` and rebuild your sources using `make world`.
6252 Today, the RSA algorithm is free for use in USA and other countries. In the past it was protected by a patent.
6256 <!-- XXX: someone revise this and add words about pf. I've no clue about this stuff -->
6258 ***Written by Nik Clayton. ***
6260 Creating a VPN between two networks, separated by the Internet, using DragonFly gateways.
6262 ### Understanding IPsec
6264 ***Written by Hiten M. Pandya. ***
6266 This section will guide you through the process of setting up IPsec, and to use it in an environment which consists of DragonFly and **Microsoft® Windows® 2000/XP** machines, to make them communicate securely. In order to set up IPsec, it is necessary that you are familiar with the concepts of building a custom kernel (see [kernelconfig.html Chapter 9]).
6268 ***IPsec*** is a protocol which sits on top of the Internet Protocol (IP) layer. It allows two or more hosts to communicate in a secure manner (hence the name). The DragonFly IPsec ***network stack*** is based on the [KAME](http://www.kame.net/) implementation, which has support for both protocol families, IPv4 and IPv6.
6270 IPsec consists of two sub-protocols:
6272 * ***Encapsulated Security Payload (ESP)***, protects the IP packet data from third party interference, by encrypting the contents using symmetric cryptography algorithms (like Blowfish, 3DES).
6274 * ***Authentication Header (AH)***, protects the IP packet header from third party interference and spoofing, by computing a cryptographic checksum and hashing the IP packet header fields with a secure hashing function. This is then followed by an additional header that contains the hash, to allow the information in the packet to be authenticated.
6276 ESP and AH can either be used together or separately, depending on the environment.
6278 IPsec can either be used to directly encrypt the traffic between two hosts (known as ***Transport Mode***); or to build ***virtual tunnels*** between two subnets, which could be used for secure communication between two corporate networks (known as ***Tunnel Mode***). The latter is more commonly known as a ***Virtual Private Network (VPN)***. The [ipsec(4)](http://leaf.dragonflybsd.org/cgi/web-man?command#ipsec§ion4) manual page should be consulted for detailed information on the IPsec subsystem in DragonFly.
6280 To add IPsec support to your kernel, add the following options to your kernel configuration file:
6284 options IPSEC #IP security
6286 options IPSEC_ESP #IP security (crypto; define w/ IPSEC)
6290 If IPsec debugging support is desired, the following kernel option should also be added:
6294 options IPSEC_DEBUG #debug for IP security
6300 There's no standard for what constitutes a VPN. VPNs can be implemented using a number of different technologies, each of which have their own strengths and weaknesses. This article presents a number of scenarios, and strategies for implementing a VPN for each scenario.
6302 ### Scenario #1: Two networks, connected to the Internet, to behave as one
6304 This is the scenario that caused me to first investigating VPNs. The premise is as follows:
6306 * You have at least two sites
6308 * Both sites are using IP internally
6310 * Both sites are connected to the Internet, through a gateway that is running DragonFly.
6312 * The gateway on each network has at least one public IP address.
6314 * The internal addresses of the two networks can be public or private IP addresses, it doesn't matter. You can be running NAT on the gateway machine if necessary.
6316 * The internal IP addresses of the two networks ***do not collide***. While I expect it is theoretically possible to use a combination of VPN technology and NAT to get this to work, I expect it to be a configuration nightmare.
6318 If you find that you are trying to connect two networks, both of which, internally, use the same private IP address range (e.g., both of them use `192.168.1.x`), then one of the networks will have to be renumbered.
6320 The network topology might look something like this:
6322 security/ipsec-network.png
6324 Notice the two public IP addresses. I'll use the letters to refer to them in the rest of this article. Anywhere you see those letters in this article, replace them with your own public IP addresses. Note also that internally, the two gateway machines have .1 IP addresses, and that the two networks have different private IP addresses (`192.168.1.x` and `192.168.2.x` respectively). All the machines on the private networks have been configured to use the `.1` machine as their default gateway.
6326 The intention is that, from a network point of view, each network should view the machines on the other network as though they were directly attached the same router -- albeit a slightly slow router with an occasional tendency to drop packets.
6328 This means that (for example), machine `192.168.1.20` should be able to run
6334 and have it work, transparently. Windows machines should be able to see the machines on the other network, browse file shares, and so on, in exactly the same way that they can browse machines on the local network.
6336 And the whole thing has to be secure. This means that traffic between the two networks has to be encrypted.
6338 Creating a VPN between these two networks is a multi-step process. The stages are as follows:
6340 1. Create a ***virtual*** network link between the two networks, across the Internet. Test it, using tools like [ping(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#ping§ion8), to make sure it works.
6342 1. Apply security policies to ensure that traffic between the two networks is transparently encrypted and decrypted as necessary. Test this, using tools like [tcpdump(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#tcpdump§ion1), to ensure that traffic is encrypted.
6344 1. Configure additional software on the DragonFly gateways, to allow Windows machines to see one another across the VPN.
6346 #### Step 1: Creating and testing a ***virtual*** network link
6348 Suppose that you were logged in to the gateway machine on network #1 (with public IP address `A.B.C.D`, private IP address `192.168.1.1`), and you ran `ping 192.168.2.1`, which is the private address of the machine with IP address `W.X.Y.Z`. What needs to happen in order for this to work?
6350 1. The gateway machine needs to know how to reach `192.168.2.1`. In other words, it needs to have a route to `192.168.2.1`.
6352 1. Private IP addresses, such as those in the `192.168.x` range are not supposed to appear on the Internet at large. Instead, each packet you send to `192.168.2.1` will need to be wrapped up inside another packet. This packet will need to appear to be from `A.B.C.D`, and it will have to be sent to `W.X.Y.Z`. This process is called ***encapsulation***.
6354 1. Once this packet arrives at `W.X.Y.Z` it will need to ***unencapsulated***, and delivered to `192.168.2.1`.
6356 You can think of this as requiring a ***tunnel*** between the two networks. The two ***tunnel mouths*** are the IP addresses `A.B.C.D` and `W.X.Y.Z`, and the tunnel must be told the addresses of the private IP addresses that will be allowed to pass through it. The tunnel is used to transfer traffic with private IP addresses across the public Internet.
6358 This tunnel is created by using the generic interface, or `gif` devices on DragonFly. As you can imagine, the `gif` interface on each gateway host must be configured with four IP addresses; two for the public IP addresses, and two for the private IP addresses.
6360 Support for the gif device must be compiled in to the DragonFly kernel on both machines. You can do this by adding the line:
6366 to the kernel configuration files on both machines, and then compile, install, and reboot as normal.
6368 Configuring the tunnel is a two step process. First the tunnel must be told what the outside (or public) IP addresses are, using [gifconfig(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#gifconfig§ion8). Then the private IP addresses must be configured using [ifconfig(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=ifconfig§ion=8).
6370 On the gateway machine on network #1 you would run the following two commands to configure the tunnel.
6374 gifconfig gif0 A.B.C.D W.X.Y.Z
6376 ifconfig gif0 inet 192.168.1.1 192.168.2.1 netmask 0xffffffff
6380 On the other gateway machine you run the same commands, but with the order of the IP addresses reversed.
6384 gifconfig gif0 W.X.Y.Z A.B.C.D
6386 ifconfig gif0 inet 192.168.2.1 192.168.1.1 netmask 0xffffffff
6396 to see the configuration. For example, on the network #1 gateway, you would see this:
6402 gif0: flags=8011<UP,POINTTOPOINT,MULTICAST> mtu 1280
6404 inet 192.168.1.1 --> 192.168.2.1 netmask 0xffffffff
6406 physical address inet A.B.C.D --> W.X.Y.Z
6410 As you can see, a tunnel has been created between the physical addresses `A.B.C.D` and `W.X.Y.Z`, and the traffic allowed through the tunnel is that between `192.168.1.1` and `192.168.2.1`.
6412 This will also have added an entry to the routing table on both machines, which you can examine with the command `netstat -rn`. This output is from the gateway host on network #1.
6424 Destination Gateway Flags Refs Use Netif Expire
6428 192.168.2.1 192.168.1.1 UH 0 0 gif0
6434 As the ***Flags*** value indicates, this is a host route, which means that each gateway knows how to reach the other gateway, but they do not know how to reach the rest of their respective networks. That problem will be fixed shortly.
6436 It is likely that you are running a firewall on both machines. This will need to be circumvented for your VPN traffic. You might want to allow all traffic between both networks, or you might want to include firewall rules that protect both ends of the VPN from one another.
6438 It greatly simplifies testing if you configure the firewall to allow all traffic through the VPN. You can always tighten things up later. If you are using [ipfw(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#ipfw§ion8) on the gateway machines then a command like
6442 ipfw add 1 allow ip from any to any via gif0
6444 will allow all traffic between the two end points of the VPN, without affecting your other firewall rules. Obviously you will need to run this command on both gateway hosts.
6446 This is sufficient to allow each gateway machine to ping the other. On `192.168.1.1`, you should be able to run
6452 and get a response, and you should be able to do the same thing on the other gateway machine.
6454 However, you will not be able to reach internal machines on either network yet. This is because of the routing -- although the gateway machines know how to reach one another, they do not know how to reach the network behind each one.
6456 To solve this problem you must add a static route on each gateway machine. The command to do this on the first gateway would be:
6460 route add 192.168.2.0 192.168.2.1 netmask 0xffffff00
6464 This says ***In order to reach the hosts on the network `192.168.2.0`, send the packets to the host `192.168.2.1`***. You will need to run a similar command on the other gateway, but with the `192.168.1.x` addresses instead.
6466 IP traffic from hosts on one network will now be able to reach hosts on the other network.
6468 That has now created two thirds of a VPN between the two networks, in as much as it is ***virtual*** and it is a ***network***. It is not private yet. You can test this using [ping(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#ping§ion8) and [tcpdump(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=tcpdump§ion=1). Log in to the gateway host and run
6472 tcpdump dst host 192.168.2.1
6474 In another log in session on the same host run
6480 You will see output that looks something like this:
6484 16:10:24.018080 192.168.1.1 > 192.168.2.1: icmp: echo request
6486 16:10:24.018109 192.168.1.1 > 192.168.2.1: icmp: echo reply
6488 16:10:25.018814 192.168.1.1 > 192.168.2.1: icmp: echo request
6490 16:10:25.018847 192.168.1.1 > 192.168.2.1: icmp: echo reply
6492 16:10:26.028896 192.168.1.1 > 192.168.2.1: icmp: echo request
6494 16:10:26.029112 192.168.1.1 > 192.168.2.1: icmp: echo reply
6498 As you can see, the ICMP messages are going back and forth unencrypted. If you had used the `-s` parameter to [tcpdump(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#tcpdump§ion1) to grab more bytes of data from the packets you would see more information.
6500 Obviously this is unacceptable. The next section will discuss securing the link between the two networks so that it all traffic is automatically encrypted.
6504 * Configure both kernels with ***pseudo-device gif***.
6506 * Edit `/etc/rc.conf` on gateway host #1 and add the following lines (replacing IP addresses as necessary).
6510 gifconfig_gif0="A.B.C.D W.X.Y.Z"
6512 ifconfig_gif0="inet 192.168.1.1 192.168.2.1 netmask 0xffffffff"
6516 route_vpn="192.168.2.0 192.168.2.1 netmask 0xffffff00"
6520 * Edit your firewall script (`/etc/rc.firewall`, or similar) on both hosts, and add
6524 ipfw add 1 allow ip from any to any via gif0
6528 * Make similar changes to `/etc/rc.conf` on gateway host #2, reversing the order of IP addresses.
6530 #### Step 2: Securing the link
6532 To secure the link we will be using IPsec. IPsec provides a mechanism for two hosts to agree on an encryption key, and to then use this key in order to encrypt data between the two hosts.
6534 The are two areas of configuration to be considered here.
6536 1. There must be a mechanism for two hosts to agree on the encryption mechanism to use. Once two hosts have agreed on this mechanism there is said to be a ***security association*** between them.
6538 1. There must be a mechanism for specifying which traffic should be encrypted. Obviously, you don't want to encrypt all your outgoing traffic -- you only want to encrypt the traffic that is part of the VPN. The rules that you put in place to determine what traffic will be encrypted are called ***security policies***.
6540 Security associations and security policies are both maintained by the kernel, and can be modified by userland programs. However, before you can do this you must configure the kernel to support IPsec and the Encapsulated Security Payload (ESP) protocol. This is done by configuring a kernel with:
6550 and recompiling, reinstalling, and rebooting. As before you will need to do this to the kernels on both of the gateway hosts.
6552 You have two choices when it comes to setting up security associations. You can configure them by hand between two hosts, which entails choosing the encryption algorithm, encryption keys, and so forth, or you can use daemons that implement the Internet Key Exchange protocol (IKE) to do this for you.
6554 I recommend the latter. Apart from anything else, it is easier to set up.
6556 Editing and displaying security policies is carried out using [setkey(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#setkey§ion8). By analogy, `setkey` is to the kernel's security policy tables as [route(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=route§ion=8) is to the kernel's routing tables. `setkey` can also display the current security associations, and to continue the analogy further, is akin to `netstat -r` in that respect.
6558 There are a number of choices for daemons to manage security associations with DragonFly. This article will describe how to use one of these, racoon. racoon is in the FreeBSD ports collection, in the security/ category, and is installed in the usual way.
6560 racoon must be run on both gateway hosts. On each host it is configured with the IP address of the other end of the VPN, and a secret key (which you choose, and must be the same on both gateways).
6562 The two daemons then contact one another, confirm that they are who they say they are (by using the secret key that you configured). The daemons then generate a new secret key, and use this to encrypt the traffic over the VPN. They periodically change this secret, so that even if an attacker were to crack one of the keys (which is as theoretically close to unfeasible as it gets) it won't do them much good -- by the time they've cracked the key the two daemons have chosen another one.
6564 racoon's configuration is stored in `${PREFIX}/etc/racoon`. You should find a configuration file there, which should not need to be changed too much. The other component of racoon's configuration, which you will need to change, is the ***pre-shared key***.
6566 The default racoon configuration expects to find this in the file `${PREFIX}/etc/racoon/psk.txt`. It is important to note that the pre-shared key is ***not*** the key that will be used to encrypt your traffic across the VPN link, it is simply a token that allows the key management daemons to trust one another.
6568 `psk.txt` contains a line for each remote site you are dealing with. In this example, where there are two sites, each `psk.txt` file will contain one line (because each end of the VPN is only dealing with one other end).
6570 On gateway host #1 this line should look like this:
6576 That is, the ***public*** IP address of the remote end, whitespace, and a text string that provides the secret. Obviously, you shouldn't use ***secret*** as your key -- the normal rules for choosing a password apply.
6578 On gateway host #2 the line would look like this
6584 That is, the public IP address of the remote end, and the same secret key. `psk.txt` must be mode `0600` (i.e., only read/write to `root`) before racoon will run.
6586 You must run racoon on both gateway machines. You will also need to add some firewall rules to allow the IKE traffic, which is carried over UDP to the ISAKMP (Internet Security Association Key Management Protocol) port. Again, this should be fairly early in your firewall ruleset.
6590 ipfw add 1 allow udp from A.B.C.D to W.X.Y.Z isakmp
6592 ipfw add 1 allow udp from W.X.Y.Z to A.B.C.D isakmp
6596 Once racoon is running you can try pinging one gateway host from the other. The connection is still not encrypted, but racoon will then set up the security associations between the two hosts -- this might take a moment, and you may see this as a short delay before the ping commands start responding.
6598 Once the security association has been set up you can view it using [setkey(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#setkey§ion8). Run
6604 on either host to view the security association information.
6606 That's one half of the problem. They other half is setting your security policies.
6608 To create a sensible security policy, let's review what's been set up so far. This discussions hold for both ends of the link.
6610 Each IP packet that you send out has a header that contains data about the packet. The header includes the IP addresses of both the source and destination. As we already know, private IP addresses, such as the `192.168.x.y` range are not supposed to appear on the public Internet. Instead, they must first be encapsulated inside another packet. This packet must have the public source and destination IP addresses substituted for the private addresses.
6612 So if your outgoing packet started looking like this:
6614 security/ipsec-out-pkt.png
6616 Then it will be encapsulated inside another packet, looking something like this:
6618 security/ipsec-encap-pkt.png
6620 This encapsulation is carried out by the `gif` device. As you can see, the packet now has real IP addresses on the outside, and our original packet has been wrapped up as data inside the packet that will be put out on the Internet.
6622 Obviously, we want all traffic between the VPNs to be encrypted. You might try putting this in to words, as:
6624 ***If a packet leaves from `A.B.C.D`, and it is destined for `W.X.Y.Z`, then encrypt it, using the necessary security associations.***
6626 ***If a packet arrives from `W.X.Y.Z`, and it is destined for `A.B.C.D`, then decrypt it, using the necessary security associations.***
6628 That's close, but not quite right. If you did this, all traffic to and from `W.X.Y.Z`, even traffic that was not part of the VPN, would be encrypted. That's not quite what you want. The correct policy is as follows
6630 ***If a packet leaves from `A.B.C.D`, and that packet is encapsulating another packet, and it is destined for `W.X.Y.Z`, then encrypt it, using the necessary security associations.***
6632 ***If a packet arrives from `W.X.Y.Z`, and that packet is encapsulating another packet, and it is destined for `A.B.C.D`, then encrypt it, using the necessary security associations.***
6634 A subtle change, but a necessary one.
6636 Security policies are also set using [setkey(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#setkey§ion8). [setkey(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=setkey§ion=8) features a configuration language for defining the policy. You can either enter configuration instructions via stdin, or you can use the `-f` option to specify a filename that contains configuration instructions.
6638 The configuration on gateway host #1 (which has the public IP address `A.B.C.D`) to force all outbound traffic to `W.X.Y.Z` to be encrypted is:
6642 spdadd A.B.C.D/32 W.X.Y.Z/32 ipencap -P out ipsec esp/tunnel/A.B.C.D-W.X.Y.Z/require;
6646 Put these commands in a file (e.g., `/etc/ipsec.conf`) and then run
6650 # setkey -f /etc/ipsec.conf
6652 `spdadd` tells [setkey(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#setkey§ion8) that we want to add a rule to the secure policy database. The rest of this line specifies which packets will match this policy. `A.B.C.D/32` and `W.X.Y.Z/32` are the IP addresses and netmasks that identify the network or hosts that this policy will apply to. In this case, we want it to apply to traffic between these two hosts. `ipencap` tells the kernel that this policy should only apply to packets that encapsulate other packets. `-P out` says that this policy applies to outgoing packets, and `ipsec` says that the packet will be secured.
6654 The second line specifies how this packet will be encrypted. `esp` is the protocol that will be used, while `tunnel` indicates that the packet will be further encapsulated in an IPsec packet. The repeated use of `A.B.C.D` and `W.X.Y.Z` is used to select the security association to use, and the final `require` mandates that packets must be encrypted if they match this rule.
6656 This rule only matches outgoing packets. You will need a similar rule to match incoming packets.
6660 spdadd W.X.Y.Z/32 A.B.C.D/32 ipencap -P in ipsec esp/tunnel/W.X.Y.Z-A.B.C.D/require;
6662 Note the `in` instead of `out` in this case, and the necessary reversal of the IP addresses.
6664 The other gateway host (which has the public IP address `W.X.Y.Z`) will need similar rules.
6668 spdadd W.X.Y.Z/32 A.B.C.D/32 ipencap -P out ipsec esp/tunnel/W.X.Y.Z-A.B.C.D/require;
6670 spdadd A.B.C.D/32 W.X.Y.Z/32 ipencap -P in ipsec esp/tunnel/A.B.C.D-W.X.Y.Z/require;
6672 Finally, you need to add firewall rules to allow ESP and IPENCAP packets back and forth. These rules will need to be added to both hosts.
6676 ipfw add 1 allow esp from A.B.C.D to W.X.Y.Z
6678 ipfw add 1 allow esp from W.X.Y.Z to A.B.C.D
6680 ipfw add 1 allow ipencap from A.B.C.D to W.X.Y.Z
6682 ipfw add 1 allow ipencap from W.X.Y.Z to A.B.C.D
6686 Because the rules are symmetric you can use the same rules on each gateway host.
6688 Outgoing packets will now look something like this:
6690 security/ipsec-crypt-pkt.png
6692 When they are received by the far end of the VPN they will first be decrypted (using the security associations that have been negotiated by racoon). Then they will enter the `gif` interface, which will unwrap the second layer, until you are left with the innermost packet, which can then travel in to the inner network.
6694 You can check the security using the same [ping(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#ping§ion8) test from earlier. First, log in to the `A.B.C.D` gateway machine, and run:
6698 tcpdump dst host 192.168.2.1
6700 In another log in session on the same host run
6706 This time you should see output like the following:
6712 Now, as you can see, [tcpdump(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#tcpdump§ion1) shows the ESP packets. If you try to examine them with the `-s` option you will see (apparently) gibberish, because of the encryption.
6714 Congratulations. You have just set up a VPN between two remote sites.
6718 * Configure both kernels with:
6728 * Install [`security/racoon`](http://pkgsrc.se/security/racoon). Edit `${PREFIX}/etc/racoon/psk.txt` on both gateway hosts, adding an entry for the remote host's IP address and a secret key that they both know. Make sure this file is mode 0600.
6730 * Add the following lines to `/etc/rc.conf` on each host:
6736 ipsec_file="/etc/ipsec.conf"
6740 * Create an `/etc/ipsec.conf` on each host that contains the necessary spdadd lines. On gateway host #1 this would be:
6744 spdadd A.B.C.D/32 W.X.Y.Z/32 ipencap -P out ipsec
6746 esp/tunnel/A.B.C.D-W.X.Y.Z/require;
6748 spdadd W.X.Y.Z/32 A.B.C.D/32 ipencap -P in ipsec
6750 esp/tunnel/W.X.Y.Z-A.B.C.D/require;
6754 On gateway host #2 this would be:
6758 spdadd W.X.Y.Z/32 A.B.C.D/32 ipencap -P out ipsec
6760 esp/tunnel/W.X.Y.Z-A.B.C.D/require;
6762 spdadd A.B.C.D/32 W.X.Y.Z/32 ipencap -P in ipsec
6764 esp/tunnel/A.B.C.D-W.X.Y.Z/require;
6768 * Add firewall rules to allow IKE, ESP, and IPENCAP traffic to both hosts:
6772 ipfw add 1 allow udp from A.B.C.D to W.X.Y.Z isakmp
6774 ipfw add 1 allow udp from W.X.Y.Z to A.B.C.D isakmp
6776 ipfw add 1 allow esp from A.B.C.D to W.X.Y.Z
6778 ipfw add 1 allow esp from W.X.Y.Z to A.B.C.D
6780 ipfw add 1 allow ipencap from A.B.C.D to W.X.Y.Z
6782 ipfw add 1 allow ipencap from W.X.Y.Z to A.B.C.D
6786 The previous two steps should suffice to get the VPN up and running. Machines on each network will be able to refer to one another using IP addresses, and all traffic across the link will be automatically and securely encrypted.
6792 ***Contributed by Chern Lee. ***
6794 **OpenSSH** is a set of network connectivity tools used to access remote machines securely. It can be used as a direct replacement for `rlogin`, `rsh`, `rcp`, and `telnet`. Additionally, any other TCP/IP connections can be tunneled/forwarded securely through SSH. **OpenSSH** encrypts all traffic to effectively eliminate eavesdropping, connection hijacking, and other network-level attacks.
6796 **OpenSSH** is maintained by the OpenBSD project, and is based upon SSH v1.2.12 with all the recent bug fixes and updates. It is compatible with both SSH protocols 1 and 2.
6798 ### Advantages of Using OpenSSH
6800 Normally, when using [telnet(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#telnet§ion1) or [rlogin(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=rlogin§ion=1), data is sent over the network in an clear, un-encrypted form. Network sniffers anywhere in between the client and server can steal your user/password information or data transferred in your session. **OpenSSH** offers a variety of authentication and encryption methods to prevent this from happening.
6804 Be sure to make the following addition to your `rc.conf` file:
6810 This will load [sshd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#sshd§ion8&manpath=OpenBSD+3.3), the daemon program for **OpenSSH** , the next time your system initializes. Alternatively, you can simply run directly the **sshd** daemon by typing `rcstart sshd` on the command line.
6814 The [ssh(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ssh§ion1&manpath=OpenBSD+3.3) utility works similarly to [rlogin(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=rlogin§ion=1).
6818 # ssh user@example.com
6820 Host key not found from the list of known hosts.
6822 Are you sure you want to continue connecting (yes/no)? yes
6824 Host 'example.com' added to the list of known hosts.
6826 user@example.com's password: *******
6828 The login will continue just as it would have if a session was created using `rlogin` or `telnet`. SSH utilizes a key fingerprint system for verifying the authenticity of the server when the client connects. The user is prompted to enter `yes` only when connecting for the first time. Future attempts to login are all verified against the saved fingerprint key. The SSH client will alert you if the saved fingerprint differs from the received fingerprint on future login attempts. The fingerprints are saved in `~/.ssh/known_hosts`, or `~/.ssh/known_hosts2` for SSH v2 fingerprints.
6830 By default, **OpenSSH** servers are configured to accept both SSH v1 and SSH v2 connections. The client, however, can choose between the two. Version 2 is known to be more robust and secure than its predecessor.
6832 The [ssh(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ssh§ion1&manpath=OpenBSD+3.3) command can be forced to use either protocol by passing it the `-1` or `-2` argument for v1 and v2, respectively.
6836 The [scp(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#scp§ion1&manpath=OpenBSD+3.3) command works similarly to [rcp(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=rcp§ion=1); it copies a file to or from a remote machine, except in a secure fashion.
6840 # scp user@example.com:/COPYRIGHT COPYRIGHT
6842 user@example.com's password: *******
6844 COPYRIGHT 100% |*****************************| 4735
6850 Since the fingerprint was already saved for this host in the previous example, it is verified when using [scp(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#scp§ion1&manpath=OpenBSD+3.3) here.
6852 The arguments passed to [scp(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#scp§ion1&manpath=OpenBSD+3.3) are similar to [cp(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=cp§ion=1), with the file or files in the first argument, and the destination in the second. Since the file is fetched over the network, through SSH, one or more of the file arguments takes on the form `user@host:<path_to_remote_file>`. The `user@` part is optional. If omitted, it will default to the same username as you are currently logged in as, unless configured otherwise.
6856 The system-wide configuration files for both the **OpenSSH** daemon and client reside within the `/etc/ssh` directory.
6858 `ssh_config` configures the client settings, while `sshd_config` configures the daemon.
6860 Additionally, the `sshd_program` (`/usr/sbin/sshd` by default), and `sshd_flags` `rc.conf` options can provide more levels of configuration.
6862 Each user can have a personal configuration file in `~/.ssh/config`. The file can configure various client options, and can include host-specific options. With the following configuration file, a user could type `ssh shell` which would be equivalent to `ssh -X user@shell.example.com`.
6868 Hostname shell.example.com
6878 Instead of using passwords, [ssh-keygen(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ssh-keygen§ion1&manpath=OpenBSD+3.3) can be used to generate RSA keys to authenticate a user:
6882 % ssh-keygen -t rsa1
6884 Initializing random number generator...
6886 Generating p: .++ (distance 66)
6888 Generating q: ..............................++ (distance 498)
6890 Computing the keys...
6892 Key generation complete.
6894 Enter file in which to save the key (/home/user/.ssh/identity):
6898 Enter the same passphrase again:
6900 Your identification has been saved in /home/user/.ssh/identity.
6904 [ssh-keygen(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ssh-keygen§ion1&manpath=OpenBSD+3.3) will create a public and private key pair for use in authentication. The private key is stored in `~/.ssh/identity`, whereas the public key is stored in `~/.ssh/identity.pub`. The public key must be placed in `~/.ssh/authorized_keys` of the remote machine in order for the setup to work.
6906 This will allow connection to the remote machine based upon RSA authentication instead of passwords.
6908 **Note:** The `-t rsa1` option will create RSA keys for use by SSH protocol version 1. If you want to use RSA keys with the SSH protocol version 2, you have to use the command `ssh-keygen -t rsa`.
6910 If a passphrase is used in [ssh-keygen(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ssh-keygen§ion1&manpath=OpenBSD+3.3), the user will be prompted for a password each time in order to use the private key.
6912 A SSH protocol version 2 DSA key can be created for the same purpose by using the `ssh-keygen -t dsa` command. This will create a public/private DSA key for use in SSH protocol version 2 sessions only. The public key is stored in `~/.ssh/id_dsa.pub`, while the private key is in `~/.ssh/id_dsa`.
6914 DSA public keys are also placed in `~/.ssh/authorized_keys` on the remote machine.
6916 [ssh-agent(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ssh-agent§ion1&manpath=OpenBSD+3.3) and [ssh-add(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ssh-add§ion=1&manpath=OpenBSD+3.3) are utilities used in managing multiple passworded private keys.
6918 **Warning:** The various options and files can be different according to the **OpenSSH** version you have on your system, to avoid problems you should consult the [ssh-keygen(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ssh-keygen§ion1&manpath=OpenBSD+3.3) manual page.
6922 **OpenSSH** has the ability to create a tunnel to encapsulate another protocol in an encrypted session.
6924 The following command tells [ssh(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ssh§ion1&manpath=OpenBSD+3.3) to create a tunnel for **telnet** :
6928 % ssh -2 -N -f -L 5023:localhost:23 user@foo.example.com
6932 The `ssh` command is used with the following options:
6936 :: Forces `ssh` to use version 2 of the protocol. (Do not use if you are working with older SSH servers)
6940 :: Indicates no command, or tunnel only. If omitted, `ssh` would initiate a normal session.
6944 :: Forces `ssh` to run in the background.
6948 :: Indicates a local tunnel in `***localport:remotehost:remoteport***` fashion.
6950 `user@foo.example.com`
6952 :: The remote SSH server.
6954 An SSH tunnel works by creating a listen socket on `localhost` on the specified port. It then forwards any connection received on the local host/port via the SSH connection to the specified remote host and port.
6956 In the example, port `***5023***` on `localhost` is being forwarded to port `***23***` on `localhost` of the remote machine. Since `***23***` is **telnet** , this would create a secure **telnet** session through an SSH tunnel.
6958 This can be used to wrap any number of insecure TCP protocols such as SMTP, POP3, FTP, etc.
6960 **Example 10-1. Using SSH to Create a Secure Tunnel for SMTP**
6964 % ssh -2 -N -f -L 5025:localhost:25 user@mailserver.example.com
6966 user@mailserver.example.com's password: *****
6968 % telnet localhost 5025
6972 Connected to localhost.
6974 Escape character is '^]'.
6976 220 mailserver.example.com ESMTP
6978 This can be used in conjunction with an [ssh-keygen(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ssh-keygen§ion1&manpath=OpenBSD+3.3) and additional user accounts to create a more seamless/hassle-free SSH tunneling environment. Keys can be used in place of typing a password, and the tunnels can be run as a separate user.
6980 #### Practical SSH Tunneling Examples
6982 ##### Secure Access of a POP3 Server
6984 At work, there is an SSH server that accepts connections from the outside. On the same office network resides a mail server running a POP3 server. The network, or network path between your home and office may or may not be completely trustable. Because of this, you need to check your e-mail in a secure manner. The solution is to create an SSH connection to your office's SSH server, and tunnel through to the mail server.
6988 % ssh -2 -N -f -L 2110:mail.example.com:110 user@ssh-server.example.com
6990 user@ssh-server.example.com's password: ******
6992 When the tunnel is up and running, you can point your mail client to send POP3 requests to `localhost` port 2110. A connection here will be forwarded securely across the tunnel to `mail.example.com`.
6994 ##### Bypassing a Draconian Firewall
6996 Some network administrators impose extremely draconian firewall rules, filtering not only incoming connections, but outgoing connections. You may be only given access to contact remote machines on ports 22 and 80 for SSH and web surfing.
6998 You may wish to access another (perhaps non-work related) service, such as an Ogg Vorbis server to stream music. If this Ogg Vorbis server is streaming on some other port than 22 or 80, you will not be able to access it.
7000 The solution is to create an SSH connection to a machine outside of your network's firewall, and use it to tunnel to the Ogg Vorbis server.
7004 % ssh -2 -N -f -L 8888:music.example.com:8000 user@unfirewalled-system.example.org
7006 user@unfirewalled-system.example.org's password: *******
7008 Your streaming client can now be pointed to `localhost` port 8888, which will be forwarded over to `music.example.com` port 8000, successfully evading the firewall.
7010 ***Contributed by Matteo Riondato. Updated for DragonFly by Dario Banno.***
7016 This chapter will provide an explanation of what DragonFly jails are and how to use them. Jails, sometimes referred to as an enhanced replacement of chroot environments, are a very powerful tool for system administrators, but their basic usage can also be useful for advanced users.
7018 After reading this chapter, you will know:
7020 * What a jail is, and what purpose it may serve in DragonFly installations.
7022 * How to build, start, and stop a jail.
7024 * The basics of jail administration, both from inside and outside the jail.
7027 Other sources of useful information about jails are:
7029 * The [jail(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=jail§ion=8) manual page. This is the full reference of the jail utility -- the administrative tool which can be used in DragonFly to start, stop, and control DragonFly jails.
7031 * The mailing lists and their archives. The archives of the DragonFly general questions mailing list and other mailing lists hosted by the DragonFly list server already contain a wealth of material for jails. It should always be engaging to search the archives, or post a new question to the [users mailing list](mailto:users@lists.dragonflybsd.org).
7035 For information on how to setup a jail, see: [Setting up a jail](http://www.youtube.com/watch?v=s4_dJjfwtR4)
7039 ## Terms Related to Jails
7041 To facilitate better understanding of parts of the DragonFly system related to jails, their internals and the way they interact with the rest of DragonFly, the following terms are used further in this chapter:
7043 ***[chroot(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=chroot§ion=8) (command)***
7045 A system call of DragonFly, which changes the root directory of a process and all its descendants.
7049 ***[chroot(2)](http://leaf.dragonflybsd.org/cgi/web-man?command=chroot§ion=2) (environment)***
7051 The environment of processes running in a “chroot”. This includes resources such as the part of the file system which is visible, user and group IDs which are available, network interfaces and other IPC mechanisms, etc.
7055 *** [jail(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=jail§ion=8) (command)***
7057 The system administration utility which allows launching of processes within a jail environment.
7061 ***host (system, process, user, etc.)***
7063 The controlling system of a jail environment. The host system has access to all the hardware resources available, and can control processes both outside of and inside a jail environment. One of the important differences of the host system from a jail is that the limitations which apply to superuser processes inside a jail are not enforced for processes of the host system.
7067 ***hosted (system, process, user, etc.)***
7069 A process, user or other entity, whose access to resources is restricted by a DragonFly jail.
7075 Since system administration is a difficult and perplexing task, many powerful tools were developed to make life easier for the administrator. These tools mostly provide enhancements of some sort to the way systems are installed, configured and maintained. Part of the tasks which an administrator is expected to do is to properly configure the security of a system, so that it can continue serving its real purpose, without allowing security violations.
7078 One of the tools which can be used to enhance the security of a DragonFly system are jails. The jail feature was written by Poul-Henning Kamp <phk@freebsd.org> for R&D Associates [[http://www.rndassociates.com/]] who contributed it to FreeBSD 4.X. Support for multiple IPs and IPv6 were introduced in DragonFly 1.7. Their development still goes on, enhancing their usefulness, performance, reliability, and security.
7082 BSD-like operating systems have had [chroot(2)](http://leaf.dragonflybsd.org/cgi/web-man?command=chroot§ion=2) since the time of 4.2BSD. The [chroot(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=chroot§ion=8) utility can be used to change the root directory of a set of processes, creating a safe environment, separate from the rest of the system. Processes created in the chrooted environment can not access files or resources outside of it. For that reason, compromising a service running in a chrooted environment should not allow the attacker to compromise the entire system. The chroot(8) utility is good for easy tasks, which do not require a lot of flexibility or complex and advanced features. Since the inception of the chroot concept, however, many ways have been found to escape from a chrooted environment and, although they have been fixed in modern versions of the DragonFly kernel, it was clear that chroot(2) was not the ideal solution for securing services. A new subsystem had to be implemented.
7084 This is one of the main reasons why ***jails*** were developed.
7086 Jails improve on the concept of the traditional [chroot(2)](http://leaf.dragonflybsd.org/cgi/web-man?command=chroot§ion=2) environment, in several ways. In a traditional [chroot(2)](http://leaf.dragonflybsd.org/cgi/web-man?command=chroot§ion=2) environment, processes are only limited in the part of the file system they can access. The rest of the system resources (like the set of system users, the running processes, or the networking subsystem) are shared by the chrooted processes and the processes of the host system. Jails expand this model by virtualizing not only access to the file system, but also the set of users, the networking subsystem of the DragonFly kernel and a few other things. A more complete set of fine-grained controls available for tuning the access of a jailed environment is described in Section 12.5.
7089 A jail is characterized by four elements:
7091 * A directory subtree -- the starting point from which a jail is entered. Once inside the jail, a process is not permitted to escape outside of this subtree. Traditional security issues which plagued the original chroot(2) design will not affect DragonFly jails.
7093 * A hostname -- the hostname which will be used within the jail. Jails are mainly used for hosting network services, therefore having a descriptive hostname for each jail can really help the system administrator.
7095 * An IP address -- this will be assigned to the jail and cannot be changed in any way during the jail's life span. The IP address of a jail is usually an alias address for an existing network interface, but this is not strictly necessary.
7097 * A command -- the path name of an executable to run inside the jail. This is relative to the root directory of the jail environment, and may vary a lot, depending on the type of the specific jail environment.
7100 Apart from these, jails can have their own set of users and their own root user. Naturally, the powers of the root user are limited within the jail environment and, from the point of view of the host system, the jail root user is not an omnipotent user. In addition, the root user of a jail is not allowed to perform critical operations to the system outside of the associated jail(8) environment. More information about capabilities and restrictions of the root user will be discussed in Section 12.5 below.
7104 ## Creating and Controlling Jails
7106 Some administrators divide jails into the following two types: ***complete*** jails, which resemble a real DragonFly system, and ***service*** jails, dedicated to one application or service, possibly running with privileges. This is only a conceptual division and the process of building a jail is not affected by it. The [jail(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=jail§ion=8) manual page is quite clear about the procedure for building a jail:
7110 # setenv D /here/is/the/jail
7113 # make installworld DESTDIR=$D (2)
7115 # make distribution DESTDIR=$D -DNO_MAKEDEV_RUN (3)
7117 # ln -sf dev/null kernel
7118 # mount_devfs -o jail $D/dev
7123 Selecting a location for a jail is the best starting point. This is where the jail will physically reside within the file system of the jail's host. A good choice can be ***/usr/jail/jailname***, where jailname is the hostname identifying the jail. The ***/usr/*** file system usually has enough space for the jail file system, which for ***complete*** jails is, essentially, a replication of every file present in a default installation of the DragonFly base system.
7128 This command will populate the directory subtree chosen as jail's physical location on the file system with the necessary binaries, libraries, manual pages and so on. Everything is done in the typical DragonFly style -- first everything is built/compiled, then installed to the destination path.
7133 The distribution target for make installs every needed configuration file. In simple words, it installs every installable file of ***/usr/src/etc/*** to the ***/etc*** directory of the jail environment: ***$D/etc/***.
7137 Once a jail is installed, it can be started by using the [jail(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=jail§ion=8) utility. The [jail(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=jail§ion=8) utility takes four mandatory arguments which are described in the Section 12.3.1. Other arguments may be specified too, e.g., to run the jailed process with the credentials of a specific user. The command argument depends on the type of the jail; for a virtual system, ***/etc/rc*** is a good choice, since it will replicate the startup sequence of a real DragonFly system. For a service jail, it depends on the service or application that will run within the jail.
7139 Jails are often started at boot time and the DragonFly rc mechanism provides an easy way to do this.
7142 A list of the jails which are enabled to start at boot time should be added to the [rc.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=rc.conf§ion=5) file:
7146 jail_enable="YES" # Set to NO to disable starting of any jails
7147 jail_list="www" # Space separated list of names of jails
7152 For each jail listed in ***jail_list***, a group of [rc.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=rc.conf§ion=5) settings, which describe the particular jail, should be added:
7156 jail_www_rootdir="/usr/jail/www" # jail's root directory
7157 jail_www_hostname="www.example.org" # jail's hostname
7158 jail_www_ip="192.168.0.10" # jail's IP address
7161 The default startup of jails configured in [rc.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=rc.conf§ion=5), will run the ***/etc/rc*** script of the jail, which assumes the jail is a complete virtual system. For service jails, the default startup command of the jail should be changed, by setting the ***jail_jailname_exec_start*** option appropriately.
7163 **Note:** For a full list of available options, please see the [rc.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=rc.conf§ion=5) manual page.
7165 The ***/etc/rc.d/jail*** script can be used to start or stop a jail by hand, if an entry for it exists in ***rc.conf***:
7167 # /etc/rc.d/jail start www
7168 # /etc/rc.d/jail stop www
7172 A clean way to shut down a [jail(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=jail§ion=8) is not available at the moment. This is because commands normally used to accomplish a clean system shutdown cannot be used inside a jail. The best way to shut down a jail is to run the following command from within the jail itself or using the [jexec(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=jexec§ion=8) utility from outside the jail:
7176 # sh /etc/rc.shutdown
7178 More information about this can be found in the [jail(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=jail§ion=8) manual page.
7182 ## Fine Tuning and Administration
7184 There are several options which can be set for any jail, and various ways of combining a host DragonFly system with jails, to produce higher level applications. This section presents some of the options available for tuning the behavior and security restrictions implemented by a jail installation.
7186 ## System tools for jail tuning in DragonFly
7188 Fine tuning of a jail's configuration is mostly done by setting [sysctl(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=sysctl§ion=8) variables. A special subtree of sysctl exists as a basis for organizing all the relevant options: the ***securityjail**** hierarchy of DragonFly kernel options. Here is a list of the main jail-related sysctls, complete with their default value. Names should be self-explanatory, but for more information about them, please refer to the [jail(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=jail§ion=8) and [sysctl(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=sysctl§ion=8) manual pages.
7190 * jail.set_hostname_allowed: 1
7192 * jail.socket_unixiproute_only: 1
7194 * jail.sysvipc_allowed: 0
7196 * jail.enforce_statfs: 2
7198 * jail.allow_raw_sockets: 0
7200 * jail.chflags_allowed: 0
7204 These variables can be used by the system administrator of the host system to add or remove some of the limitations imposed by default on the root user. Note that there are some limitations which cannot be removed. The root user is not allowed to mount or unmount file systems from within a [jail(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=jail§ion=8). The root inside a jail may not set firewall rules or do many other administrative tasks which require modifications of in-kernel data, such as setting the securelevel of the kernel.
7208 The base system of DragonFly contains a basic set of tools for viewing information about the active jails, and attaching to a jail to run administrative commands. The [jls(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=jls§ion=8) and [jexec(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=jexec§ion=8) commands are part of the base DragonFly system, and can be used to perform the following simple tasks:
7210 * Print a list of active jails and their corresponding jail identifier (JID), IP address, hostname and path.
7212 * Attach to a running jail, from its host system, and run a command inside the jail or perform administrative tasks inside the jail itself. This is especially useful when the root user wants to cleanly shut down a jail. The [jexec(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=jexec§ion=8) utility can also be used to start a shell in a jail to do administration in it; for example:
7218 ***This Page is under constructions. New software are being added regularly.***
7219 **Follow the links below to see how to make corresponding software work on DragonFly**
7226 [FTP Server](http://www.dragonflybsd.org/docs/newhandbook/FTP/)
7228 ## Installing flash player on firefox.
7230 The Flash plugin is distributed by Adobe in **binary form only**. Adobe does not provide a native DragonFlyBSD plugin, but there is a Linux plugin which you can use under Linux emulation. Linux emulation software is installed from **pkgsrc** and is tested to be working fine on x86 Platform. The steps are
7232 ### Configure Linux Support
7234 # echo "linux_load=yes" >> /boot/loader.conf
7235 # echo "linux_enable=yes" >> /etc/rc.conf
7236 # echo "proc /compat/linux/proc linprocfs rw 0 0" >> /etc/fstab
7238 **Reboot DragonFly** ( not necessarry but easier for new users ) so that Linux Emulation is loaded to the kernel and configured correctly.
7240 ### Install multimedia/libflashsupport from pkgsrc.
7242 # cd /usr/pkgsrc/multimedia/libflashsupport
7245 This will get you all packages needed for Linux Emulation. Currently the Linux Emulation package installs software from [Suse 10]( http://ftp.hosteurope.de/mirror/ftp.opensuse.org/discontinued/10.0/suse/i586/) distribution. You could see the list of packages installed using pkg_info.
7247 # pkg_info |grep suse
7248 suse_openssl-10.0nb5 Linux compatibility package for OpenSSL
7249 suse_gtk2-10.0nb4 Linux compatibility package for GTK+-2.x
7250 suse_gtk-10.0nb2 Linux compatibility package for GTK+-1.x
7251 suse_libjpeg-10.0nb2 Linux compatibility package for JPEG
7252 suse_base-10.0nb5 Linux compatibility package
7253 suse_slang-10.0nb3 Linux compatibility package for S-Lang
7254 suse_locale-10.0nb2 Linux compatibility package with locale files
7255 suse_fontconfig-10.0nb6 Linux compatibility package for fontconfig
7256 suse_libtiff-10.0nb4 Linux compatibility package for TIFF
7257 suse_openmotif-10.0nb2 Linux compatibility package for OpenMotif
7258 suse_libpng-10.0nb4 Linux compatibility package for PNG
7259 suse_libcups-10.0nb4 Linux compatibility package for CUPS
7260 suse_gdk-pixbuf-10.0nb3 Linux compatibility package for gdk-pixbuf
7261 suse_expat-10.0nb2 Linux compatibility package for expat
7262 suse_vmware-10.0nb2 Linux compatibility package to help run VMware
7263 suse_libxml2-10.0nb2 Linux compatibility package for libxml2
7264 suse_compat-10.0nb3 Linux compatibility package with old shared libraries
7265 suse_x11-10.0nb4 Linux compatibility package for X11
7266 suse_glx-10.0nb4 Linux compatibility package for OpenGL/Mesa
7267 suse_freetype2-10.0nb5 Linux compatibility package for freetype-2.x
7268 suse_aspell-10.0nb2 Linux compatibility package for aspell
7269 suse-10.0nb4 SUSE-based Linux binary emulation environment
7271 ### Install www/nspluginwrapper
7273 This will allow DragonFly to use the Linux Binary Flash Plugin
7275 # cd /usr/pkgsrc/www/nspluginwrapper
7278 ### Install multimedia/ns-flash
7280 This is the Linux Flash Plugin itself.
7282 # cd /usr/pkgsrc/multimedia/ns-flash
7283 # bmake NO_CHECKSUM=yes package
7285 You can check if the Flash plugin is installed right by.
7287 # /usr/pkg/bin/nspluginwrapper --list
7288 /usr/pkg/lib/netscape/plugins/npwrapper.libflashplayer.so
7289 Original plugin: /usr/pkg/lib/netscape/plugins/libflashplayer.so
7290 Wrapper version string: 1.2.2
7291 /usr/pkg/lib/netscape/plugins/npwrapper.libflashplayer.so
7292 Original plugin: /usr/pkg/lib/netscape/plugins/libflashplayer.so
7293 Wrapper version string: 1.2.2
7295 Don't worry if it is listed twice as above.
7297 Now Start Firefox and type "**about:plugins**" in the address bar and you should find the flash plugins listed as [shown in this Picture](http://leaf.dragonflybsd.org/~sgeorge/PICs/flash-plugin-in-firefox.png).
7299 You can watch Streaming Flash now.
7301 ## Chapter 18 Serial Communications
7304 ***Reorganized, and parts rewritten by Ivailo Mladenov. ***
7308 UNIX® has always had support for serial communications. In fact, the very first UNIX machines relied on serial lines for user input and output. Things have changed a lot from the days when the average ***terminal*** consisted of a 10-character-per-second serial printer and a keyboard. This chapter will cover some of the ways in which DragonFly uses serial communications.
7310 After reading this chapter, you will know:
7312 * How to connect terminals to your DragonFly system.
7314 * How to use a modem to dial out to remote hosts.
7316 * How to allow remote users to login to your system with a modem.
7318 * How to boot your system from a serial console.
7320 Before reading this chapter, you should:
7322 * Know how to configure and install a new kernel ([kernelconfig.html Chapter 10]).
7324 * Understand UNIX permissions and processes ([basics.html Chapter 3]).
7326 * Have access to the technical manual for the serial hardware (modem or multi-port card) that you would like to use with DragonFly.
7330 ## 18.1 Introduction
7332 ### 18.1.1 Terminology
7334 bps:: Bits per Second -- the rate at which data is transmitted;
7336 DTE:: Data Terminal Equipment -- for example, your computer;
7338 DCE:: Data Communications Equipment -- your modem;
7340 RS-232:: EIA standard for hardware serial communications.
7342 When talking about communications data rates, this section does not use the term ***baud***. Baud refers to the number of electrical state transitions that may be made in a period of time, while ***bps*** (bits per second) is the ***correct*** term to use (at least it does not seem to bother the curmudgeons quite as much).
7344 ### 18.1.2 Cables and Ports
7346 To connect a modem or terminal to your DragonFly system, you will need a serial port on your computer and the proper cable to connect to your serial device. If you are already familiar with your hardware and the cable it requires, you can safely skip this section.
7348 #### 18.1.2.1 Cables
7350 There are several different kinds of serial cables. The two most common types for our purposes are null-modem cables and standard (***straight***) RS-232 cables. The documentation for your hardware should describe the type of cable required.
7352 ##### 18.1.2.1.1 Null-modem Cables
7354 A null-modem cable passes some signals, such as ***signal ground***, straight through, but switches other signals. For example, the ***send data*** pin on one end goes to the ***receive data*** pin on the other end.
7356 If you like making your own cables, you can construct a null-modem cable for use with terminals. This table shows the RS-232C signal names and the pin numbers on a DB-25 connector.
7359 | Signal | Pin # | | Pin # | Signal
7360 SG | 7 | connects to | 7 | SG
7361 TxD | 2 | connects to | 3 | RxD
7362 RxD | 3 | connects to | 2 | TxD
7363 RTS | 4 | connects to | 5 | CTS
7364 CTS | 5 | connects to | 4 | RTS
7365 DTR | 20 | connects to | 6 | DSR
7367 DSR | 6 | connects to | 20 | DTR |
7371 **Note:** Connect ***Data Set Ready*** (DSR) and ***Data Carrier Detect*** (DCD) internally in the connector hood, and then to ***Data Terminal Ready*** (DTR) in the remote hood.
7373 ##### 18.1.2.1.2 Standard RS-232C Cables
7375 A standard serial cable passes all the RS-232C signals straight-through. That is, the ***send data*** pin on one end of the cable goes to the ***send data*** pin on the other end. This is the type of cable to use to connect a modem to your DragonFly system, and is also appropriate for some terminals.
7379 Serial ports are the devices through which data is transferred between the DragonFly host computer and the terminal. This section describes the kinds of ports that exist and how they are addressed in DragonFly.
7381 ##### 18.1.2.2.1 Kinds of Ports
7383 Several kinds of serial ports exist. Before you purchase or construct a cable, you need to make sure it will fit the ports on your terminal and on the DragonFly system.
7385 Most terminals will have DB25 ports. Personal computers, including PCs running DragonFly, will have DB25 or DB9 ports. If you have a multiport serial card for your PC, you may have RJ-12 or RJ-45 ports.
7387 See the documentation that accompanied the hardware for specifications on the kind of port in use. A visual inspection of the port often works too.
7389 ##### 18.1.2.2.2 Port Names
7391 In DragonFly, you access each serial port through an entry in the `/dev` directory. There are two different kinds of entries:
7393 * Call-in ports are named `/dev/ttyd`***N****** where `***N***` is the port number, starting from zero. Generally, you use the call-in port for terminals. Call-in ports require that the serial line assert the data carrier detect (DCD) signal to work correctly.
7395 * Call-out ports are named `/dev/cuaa`***N******. You usually do not use the call-out port for terminals, just for modems. You may use the call-out port if the serial cable or the terminal does not support the carrier detect signal.
7397 If you have connected a terminal to the first serial port (`COM1` in MS-DOS®), then you will use `/dev/ttyd0` to refer to the terminal. If the terminal is on the second serial port (also known as `COM2`), use `/dev/ttyd1`, and so forth.
7399 ### 18.1.3 Kernel Configuration
7401 DragonFly supports four serial ports by default. In the MS-DOS world, these are known as `COM1`, `COM2`, `COM3`, and `COM4`. DragonFly currently supports ***dumb*** multiport serial interface cards, such as the BocaBoard 1008 and 2016, as well as more intelligent multi-port cards such as those made by Digiboard and Stallion Technologies. However, the default kernel only looks for the standard COM ports.
7403 To see if your kernel recognizes any of your serial ports, watch for messages while the kernel is booting, or use the `/sbin/dmesg` command to replay the kernel's boot messages. In particular, look for messages that start with the characters `sio`.
7405 **Tip:** To view just the messages that have the word `sio`, use the command:
7409 # /sbin/dmesg | grep 'sio'
7411 For example, on a system with four serial ports, these are the serial-port specific kernel boot messages:
7415 sio0 at 0x3f8-0x3ff irq 4 on isa
7419 sio1 at 0x2f8-0x2ff irq 3 on isa
7423 sio2 at 0x3e8-0x3ef irq 5 on isa
7427 sio3 at 0x2e8-0x2ef irq 9 on isa
7431 If your kernel does not recognize all of your serial ports, you will probably need to configure a custom DragonFly kernel for your system. For detailed information on configuring your kernel, please see [kernelconfig.html Chapter 12].
7433 The relevant device lines for your kernel configuration file would look like this:
7437 device sio0 at isa? port IO_COM1 irq 4
7439 device sio1 at isa? port IO_COM2 irq 3
7441 device sio2 at isa? port IO_COM3 irq 5
7443 device sio3 at isa? port IO_COM4 irq 9
7445 **Note:** `port IO_COM1` is a substitution for `port 0x3f8`, `IO_COM2` is `0x2f8`, `IO_COM3` is `0x3e8`, and `IO_COM4` is `0x2e8`, which are fairly common port addresses for their respective serial ports; interrupts 4, 3, 5, and 9 are fairly common interrupt request lines. Also note that regular serial ports ***cannot*** share interrupts on ISA-bus PCs (multiport boards have on-board electronics that allow all the 16550A's on the board to share one or two interrupt request lines).
7447 ### 18.1.4 Device Special Files
7449 Most devices in the kernel are accessed through ***device special files***, which are located in the `/dev` directory. The `sio` devices are accessed through the `/dev/ttyd`***N****** (dial-in) and `/dev/cuaa`***N****** (call-out) devices. DragonFly also provides initialization devices (`/dev/ttyid`***N****** and `/dev/cuaia`***N******) and locking devices (`/dev/ttyld`***N****** and `/dev/cuala`***N******). The initialization devices are used to initialize communications port parameters each time a port is opened, such as `crtscts` for modems which use `RTS/CTS` signaling for flow control. The locking devices are used to lock flags on ports to prevent users or programs changing certain parameters; see the manual pages [termios(4)](http://leaf.dragonflybsd.org/cgi/web-man?command#termios§ion4), [sio(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=sio§ion=4), and [stty(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=stty§ion=1) for information on the terminal settings, locking and initializing devices, and setting terminal options, respectively.
7451 ### 18.1.5 Serial Port Configuration
7453 The `ttyd`***N****** (or `cuaa`***N******) device is the regular device you will want to open for your applications. When a process opens the device, it will have a default set of terminal I/O settings. You can see these settings with the command
7457 # stty -a -f /dev/ttyd1
7459 When you change the settings to this device, the settings are in effect until the device is closed. When it is reopened, it goes back to the default set. To make changes to the default set, you can open and adjust the settings of the ***initial state*** device. For example, to turn on `CLOCAL` mode, 8 bit communication, and `XON/XOFF` flow control by default for `ttyd5`, type:
7463 # stty -f /dev/ttyid5 clocal cs8 ixon ixoff
7465 System-wide initialization of the serial devices is controlled in `/etc/rc.serial`. This file affects the default settings of serial devices.
7467 To prevent certain settings from being changed by an application, make adjustments to the ***lock state*** device. For example, to lock the speed of `ttyd5` to 57600 bps, type:
7471 # stty -f /dev/ttyld5 57600
7473 Now, an application that opens `ttyd5` and tries to change the speed of the port will be stuck with 57600 bps.
7475 Naturally, you should make the initial state and lock state devices writable only by the `root` account.
7481 Terminals provide a convenient and low-cost way to access your DragonFly system when you are not at the computer's console or on a connected network. This section describes how to use terminals with DragonFly.
7483 ### 18.2.1 Uses and Types of Terminals
7485 The original UNIX® systems did not have consoles. Instead, people logged in and ran programs through terminals that were connected to the computer's serial ports. It is quite similar to using a modem and terminal software to dial into a remote system to do text-only work.
7487 Today's PCs have consoles capable of high quality graphics, but the ability to establish a login session on a serial port still exists in nearly every UNIX style operating system today; DragonFly is no exception. By using a terminal attached to an unused serial port, you can log in and run any text program that you would normally run on the console or in an `xterm` window in the X Window System.
7489 For the business user, you can attach many terminals to a DragonFly system and place them on your employees' desktops. For a home user, a spare computer such as an older IBM PC or a Macintosh® can be a terminal wired into a more powerful computer running DragonFly. You can turn what might otherwise be a single-user computer into a powerful multiple user system.
7491 For DragonFly, there are three kinds of terminals:
7493 * [ Dumb terminals](term.html#TERM-DUMB)
7495 * [ PCs acting as terminals](term.html#TERM-PCS)
7497 * [ X terminals](term.html#TERM-X)
7499 #### 18.2.1.1 Dumb Terminals
7501 Dumb terminals are specialized pieces of hardware that let you connect to computers over serial lines. They are called ***dumb*** because they have only enough computational power to display, send, and receive text. You cannot run any programs on them. It is the computer to which you connect them that has all the power to run text editors, compilers, email, games, and so forth.
7503 There are hundreds of kinds of dumb terminals made by many manufacturers, including Digital Equipment Corporation's VT-100 and Wyse's WY-75. Just about any kind will work with DragonFly. Some high-end terminals can even display graphics, but only certain software packages can take advantage of these advanced features.
7505 Dumb terminals are popular in work environments where workers do not need access to graphical applications such as those provided by the X Window System.
7507 #### 18.2.1.2 PCs Acting as Terminals
7509 If a [ dumb terminal](term.html#TERM-DUMB) has just enough ability to display, send, and receive text, then certainly any spare personal computer can be a dumb terminal. All you need is the proper cable and some ***terminal emulation*** software to run on the computer.
7511 Such a configuration is popular in homes. For example, if your spouse is busy working on your DragonFly system's console, you can do some text-only work at the same time from a less powerful personal computer hooked up as a terminal to the DragonFly system.
7513 #### 18.2.1.3 X Terminals
7515 X terminals are the most sophisticated kind of terminal available. Instead of connecting to a serial port, they usually connect to a network like Ethernet. Instead of being relegated to text-only applications, they can display any X application.
7517 We introduce X terminals just for the sake of completeness. However, this chapter does ***not*** cover setup, configuration, or use of X terminals.
7519 ### 18.2.2 Configuration
7521 This section describes what you need to configure on your DragonFly system to enable a login session on a terminal. It assumes you have already configured your kernel to support the serial port to which the terminal is connected--and that you have connected it.
7523 Recall from [boot.html Chapter 10] that the `init` process is responsible for all process control and initialization at system startup. One of the tasks performed by `init` is to read the `/etc/ttys` file and start a `getty` process on the available terminals. The `getty` process is responsible for reading a login name and starting the `login` program.
7525 Thus, to configure terminals for your DragonFly system the following steps should be taken as `root`:
7527 1. Add a line to `/etc/ttys` for the entry in the `/dev` directory for the serial port if it is not already there.
7529 1. Specify that `/usr/libexec/getty` be run on the port, and specify the appropriate `***getty***` type from the `/etc/gettytab` file.
7531 1. Specify the default terminal type.
7533 1. Set the port to ***on.***
7535 1. Specify whether the port should be ***secure.***
7537 1. Force `init` to reread the `/etc/ttys` file.
7539 As an optional step, you may wish to create a custom `***getty***` type for use in step 2 by making an entry in `/etc/gettytab`. This chapter does not explain how to do so; you are encouraged to see the [gettytab(5)](http://leaf.dragonflybsd.org/cgi/web-man?command#gettytab&section5) and the [getty(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=getty&section=8) manual pages for more information.
7541 #### 18.2.2.1 Adding an Entry to `/etc/ttys`
7543 The `/etc/ttys` file lists all of the ports on your DragonFly system where you want to allow logins. For example, the first virtual console `ttyv0` has an entry in this file. You can log in on the console using this entry. This file also contains entries for the other virtual consoles, serial ports, and pseudo-ttys. For a hardwired terminal, just list the serial port's `/dev` entry without the `/dev` part (for example, `/dev/ttyv0` would be listed as `ttyv0`).
7545 A default DragonFly install includes an `/etc/ttys` file with support for the first four serial ports: `ttyd0` through `ttyd3`. If you are attaching a terminal to one of those ports, you do not need to add another entry.
7547 **Example 17-1. Adding Terminal Entries to `/etc/ttys`**
7549 Suppose we would like to connect two terminals to the system: a Wyse-50 and an old 286 IBM PC running **Procomm** terminal software emulating a VT-100 terminal. We connect the Wyse to the second serial port and the 286 to the sixth serial port (a port on a multiport serial card). The corresponding entries in the `/etc/ttys` file would look like this:
7553 ttyd1./imagelib/callouts/1.png "/usr/libexec/getty std.38400"./imagelib/callouts/2.png wy50./imagelib/callouts/3.png on./imagelib/callouts/4.png insecure./imagelib/callouts/5.png
7555 ttyd5 "/usr/libexec/getty std.19200" vt100 on insecure
7559 [ ./imagelib/callouts/1.png](term.html#CO-TTYS-LINE1COL1):: The first field normally specifies the name of the terminal special file as it is found in `/dev`.[ ./imagelib/callouts/2.png](term.html#CO-TTYS-LINE1COL2):: The second field is the command to execute for this line, which is usually [getty(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#getty&section8). `getty` initializes and opens the line, sets the speed, prompts for a user name and then executes the [login(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=login&section=1) program.The `getty` program accepts one (optional) parameter on its command line, the `***getty***` type. A `***getty***` type configures characteristics on the terminal line, like bps rate and parity. The `getty` program reads these characteristics from the file `/etc/gettytab`.The file `/etc/gettytab` contains lots of entries for terminal lines both old and new. In almost all cases, the entries that start with the text `std` will work for hardwired terminals. These entries ignore parity. There is a `std` entry for each bps rate from 110 to 115200. Of course, you can add your own entries to this file. The [gettytab(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=gettytab&section=5) manual page provides more information.When setting the `***getty***` type in the `/etc/ttys` file, make sure that the communications settings on the terminal match.For our example, the Wyse-50 uses no parity and connects at 38400 bps. The 286 PC uses no parity and connects at 19200 bps.[ ./imagelib/callouts/3.png](term.html#CO-TTYS-LINE1COL3):: The third field is the type of terminal usually connected to that tty line. For dial-up ports, `unknown` or `dialup` is typically used in this field since users may dial up with practically any type of terminal or software. For hardwired terminals, the terminal type does not change, so you can put a real terminal type from the [termcap(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=termcap&section=5) database file in this field.For our example, the Wyse-50 uses the real terminal type while the 286 PC running **Procomm** will be set to emulate at VT-100.[ ./imagelib/callouts/4.png](term.html#CO-TTYS-LINE1COL4):: The fourth field specifies if the port should be enabled. Putting `on` here will have the `init` process start the program in the second field, `getty`. If you put `off` in this field, there will be no `getty`, and hence no logins on the port.[ ./imagelib/callouts/5.png](term.html#CO-TTYS-LINE1COL5):: The final field is used to specify whether the port is secure. Marking a port as secure means that you trust it enough to allow the `root` account (or any account with a user ID of 0) to login from that port. Insecure ports do not allow `root` logins. On an insecure port, users must login from unprivileged accounts and then use [su(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=su&section=1) or a similar mechanism to gain superuser privileges.It is highly recommended that you use ***insecure*** even for terminals that are behind locked doors. It is quite easy to login and use `su` if you need superuser privileges.
7561 #### 18.2.2.2 Force `init` to Reread `/etc/ttys`
7563 After making the necessary changes to the `/etc/ttys` file you should send a SIGHUP (hangup) signal to the `init` process to force it to re-read its configuration file. For example:
7569 **Note:** `init` is always the first process run on a system, therefore it will always have PID 1.
7571 If everything is set up correctly, all cables are in place, and the terminals are powered up, then a `getty` process should be running on each terminal and you should see login prompts on your terminals at this point.
7573 ### 18.2.3 Troubleshooting Your Connection
7575 Even with the most meticulous attention to detail, something could still go wrong while setting up a terminal. Here is a list of symptoms and some suggested fixes.
7577 #### 18.2.3.1 No Login Prompt Appears
7579 Make sure the terminal is plugged in and powered up. If it is a personal computer acting as a terminal, make sure it is running terminal emulation software on the correct serial port.
7581 Make sure the cable is connected firmly to both the terminal and the DragonFly computer. Make sure it is the right kind of cable.
7583 Make sure the terminal and DragonFly agree on the bps rate and parity settings. If you have a video display terminal, make sure the contrast and brightness controls are turned up. If it is a printing terminal, make sure paper and ink are in good supply.
7585 Make sure that a `getty` process is running and serving the terminal. For example, to get a list of running `getty` processes with `ps`, type:
7589 # ps -axww|grep getty
7591 You should see an entry for the terminal. For example, the following display shows that a `getty` is running on the second serial port `ttyd1` and is using the `std.38400` entry in `/etc/gettytab`:
7595 22189 d1 Is+ 0:00.03 /usr/libexec/getty std.38400 ttyd1
7597 If no `getty` process is running, make sure you have enabled the port in `/etc/ttys`. Also remember to run `kill -HUP 1` after modifying the `ttys` file.
7599 If the `getty` process is running but the terminal still does not display a login prompt, or if it displays a prompt but will not allow you to type, your terminal or cable may not support hardware handshaking. Try changing the entry in `/etc/ttys` from `std.38400` to `3wire.38400` remember to run `kill -HUP 1` after modifying `/etc/ttys`). The `3wire` entry is similar to `std`, but ignores hardware handshaking. You may need to reduce the baud rate or enable software flow control when using `3wire` to prevent buffer overflows.
7601 #### 18.2.3.2 If Garbage Appears Instead of a Login Prompt
7603 Make sure the terminal and DragonFly agree on the bps rate and parity settings. Check the `getty` processes to make sure the correct `***getty***` type is in use. If not, edit `/etc/ttys` and run `kill -HUP 1`.
7605 #### 18.2.3.3 Characters Appear Doubled, the Password Appears When Typed
7607 Switch the terminal (or the terminal emulation software) from ***half duplex*** or ***local echo*** to ***full duplex.***
7611 ## 18.3 Dial-in Service
7613 Configuring your DragonFly system for dial-in service is very similar to connecting terminals except that you are dealing with modems instead of terminals.
7615 ### 18.3.1 External vs. Internal Modems
7617 External modems seem to be more convenient for dial-up, because external modems often can be semi-permanently configured via parameters stored in non-volatile RAM and they usually provide lighted indicators that display the state of important RS-232 signals. Blinking lights impress visitors, but lights are also very useful to see whether a modem is operating properly.
7619 Internal modems usually lack non-volatile RAM, so their configuration may be limited only to setting DIP switches. If your internal modem has any signal indicator lights, it is probably difficult to view the lights when the system's cover is in place.
7621 #### 18.3.1.1 Modems and Cables
7623 If you are using an external modem, then you will of course need the proper cable. A standard RS-232C serial cable should suffice as long as all of the normal signals are wired:
7625 * Transmitted Data (SD)
7627 * Received Data (RD)
7629 * Request to Send (RTS)
7631 * Clear to Send (CTS)
7633 * Data Set Ready (DSR)
7635 * Data Terminal Ready (DTR)
7637 * Carrier Detect (CD)
7639 * Signal Ground (SG)
7641 DragonFly needs the RTS and CTS signals for flow-control at speeds above 2400 bps, the CD signal to detect when a call has been answered or the line has been hung up, and the DTR signal to reset the modem after a session is complete. Some cables are wired without all of the needed signals, so if you have problems, such as a login session not going away when the line hangs up, you may have a problem with your cable.
7643 Like other UNIX® like operating systems, DragonFly uses the hardware signals to find out when a call has been answered or a line has been hung up and to hangup and reset the modem after a call. DragonFly avoids sending commands to the modem or watching for status reports from the modem. If you are familiar with connecting modems to PC-based bulletin board systems, this may seem awkward.
7645 ### 18.3.2 Serial Interface Considerations
7647 DragonFly supports NS8250-, NS16450-, NS16550-, and NS16550A-based EIA RS-232C (CCITT V.24) communications interfaces. The 8250 and 16450 devices have single-character buffers. The 16550 device provides a 16-character buffer, which allows for better system performance. (Bugs in plain 16550's prevent the use of the 16-character buffer, so use 16550A's if possible). Because single-character-buffer devices require more work by the operating system than the 16-character-buffer devices, 16550A-based serial interface cards are much preferred. If the system has many active serial ports or will have a heavy load, 16550A-based cards are better for low-error-rate communications.
7649 ### 18.3.3 Quick Overview
7651 As with terminals, `init` spawns a `getty` process for each configured serial port for dial-in connections. For example, if a modem is attached to `/dev/ttyd0`, the command `ps ax` might show this:
7655 4850 ?? I 0:00.09 /usr/libexec/getty V19200 ttyd0
7657 When a user dials the modem's line and the modems connect, the CD (Carrier Detect) line is reported by the modem. The kernel notices that carrier has been detected and completes `getty`'s open of the port. `getty` sends a login: prompt at the specified initial line speed. `getty` watches to see if legitimate characters are received, and, in a typical configuration, if it finds junk (probably due to the modem's connection speed being different than `getty`'s speed), `getty` tries adjusting the line speeds until it receives reasonable characters.
7659 After the user enters his/her login name, `getty` executes `/usr/bin/login`, which completes the login by asking for the user's password and then starting the user's shell.
7661 ### 18.3.4 Configuration Files
7663 There are three system configuration files in the `/etc` directory that you will probably need to edit to allow dial-up access to your DragonFly system. The first, `/etc/gettytab`, contains configuration information for the `/usr/libexec/getty` daemon. Second, `/etc/ttys` holds information that tells `/sbin/init` what `tty` devices should have `getty` processes running on them. Lastly, you can place port initialization commands in the `/etc/rc.serial` script.
7665 There are two schools of thought regarding dial-up modems on UNIX. One group likes to configure their modems and systems so that no matter at what speed a remote user dials in, the local computer-to-modem RS-232 interface runs at a locked speed. The benefit of this configuration is that the remote user always sees a system login prompt immediately. The downside is that the system does not know what a user's true data rate is, so full-screen programs like Emacs will not adjust their screen-painting methods to make their response better for slower connections.
7667 The other school configures their modems' RS-232 interface to vary its speed based on the remote user's connection speed. For example, V.32bis (14.4 Kbps) connections to the modem might make the modem run its RS-232 interface at 19.2 Kbps, while 2400 bps connections make the modem's RS-232 interface run at 2400 bps. Because `getty` does not understand any particular modem's connection speed reporting, `getty` gives a login: message at an initial speed and watches the characters that come back in response. If the user sees junk, it is assumed that they know they should press the Enter key until they see a recognizable prompt. If the data rates do not match, `getty` sees anything the user types as ***junk***, tries going to the next speed and gives the login: prompt again. This procedure can continue ad nauseam, but normally only takes a keystroke or two before the user sees a good prompt. Obviously, this login sequence does not look as clean as the former ***locked-speed*** method, but a user on a low-speed connection should receive better interactive response from full-screen programs.
7669 This section will try to give balanced configuration information, but is biased towards having the modem's data rate follow the connection rate.
7671 #### 18.3.4.1 `/etc/gettytab`
7673 `/etc/gettytab` is a [termcap(5)](http://leaf.dragonflybsd.org/cgi/web-man?command#termcap§ion5)-style file of configuration information for [getty(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=getty§ion=8). Please see the [gettytab(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=gettytab§ion=5) manual page for complete information on the format of the file and the list of capabilities.
7675 ##### 18.3.4.1.1 Locked-speed Config
7677 If you are locking your modem's data communications rate at a particular speed, you probably will not need to make any changes to `/etc/gettytab`.
7679 ##### 18.3.4.1.2 Matching-speed Config
7681 You will need to set up an entry in `/etc/gettytab` to give `getty` information about the speeds you wish to use for your modem. If you have a 2400 bps modem, you can probably use the existing `D2400` entry.
7687 # Fast dialup terminals, 2400/1200/300 rotary (can start either way)
7691 D2400|d2400|Fast-Dial-2400:\
7693 :nx#D1200:tc2400-baud:
7695 3|D1200|Fast-Dial-1200:\
7697 :nx#D300:tc1200-baud:
7699 5|D300|Fast-Dial-300:\
7701 :nx#D2400:tc300-baud:
7703 If you have a higher speed modem, you will probably need to add an entry in `/etc/gettytab`; here is an entry you could use for a 14.4 Kbps modem with a top interface speed of 19.2 Kbps:
7709 # Additions for a V.32bis Modem
7713 um|V300|High Speed Modem at 300,8-bit:\
7715 :nx#V19200:tcstd.300:
7717 un|V1200|High Speed Modem at 1200,8-bit:\
7719 :nx#V300:tcstd.1200:
7721 uo|V2400|High Speed Modem at 2400,8-bit:\
7723 :nx#V1200:tcstd.2400:
7725 up|V9600|High Speed Modem at 9600,8-bit:\
7727 :nx#V2400:tcstd.9600:
7729 uq|V19200|High Speed Modem at 19200,8-bit:\
7731 :nx#V9600:tcstd.19200:
7733 This will result in 8-bit, no parity connections.
7735 The example above starts the communications rate at 19.2 Kbps (for a V.32bis connection), then cycles through 9600 bps (for V.32), 2400 bps, 1200 bps, 300 bps, and back to 19.2 Kbps. Communications rate cycling is implemented with the `nx#` (***next table***) capability. Each of the lines uses a `tc` (***table continuation***) entry to pick up the rest of the ***standard*** settings for a particular data rate.
7737 If you have a 28.8 Kbps modem and/or you want to take advantage of compression on a 14.4 Kbps modem, you need to use a higher communications rate than 19.2 Kbps. Here is an example of a `gettytab` entry starting a 57.6 Kbps:
7743 # Additions for a V.32bis or V.34 Modem
7745 # Starting at 57.6 Kbps
7749 vm|VH300|Very High Speed Modem at 300,8-bit:\
7751 :nx#VH57600:tcstd.300:
7753 vn|VH1200|Very High Speed Modem at 1200,8-bit:\
7755 :nx#VH300:tcstd.1200:
7757 vo|VH2400|Very High Speed Modem at 2400,8-bit:\
7759 :nx#VH1200:tcstd.2400:
7761 vp|VH9600|Very High Speed Modem at 9600,8-bit:\
7763 :nx#VH2400:tcstd.9600:
7765 vq|VH57600|Very High Speed Modem at 57600,8-bit:\
7767 :nx#VH9600:tcstd.57600:
7769 If you have a slow CPU or a heavily loaded system and do not have 16550A-based serial ports, you may receive ***`sio`*** ***silo*** errors at 57.6 Kbps.
7771 #### 18.3.4.2 `/etc/ttys`
7773 Configuration of the `/etc/ttys` file was covered in [ Example 17-1](term.html#EX-ETC-TTYS). Configuration for modems is similar but we must pass a different argument to `getty` and specify a different terminal type. The general format for both locked-speed and matching-speed configurations is:
7777 ttyd0 "/usr/libexec/getty `***xxx***`" dialup on
7779 The first item in the above line is the device special file for this entry -- `ttyd0` means `/dev/ttyd0` is the file that this `getty` will be watching. The second item, `"/usr/libexec/getty `***xxx***`"` (`***xxx***` will be replaced by the initial `gettytab` capability) is the process `init` will run on the device. The third item, `dialup`, is the default terminal type. The fourth parameter, `on`, indicates to `init` that the line is operational. There can be a fifth parameter, `secure`, but it should only be used for terminals which are physically secure (such as the system console).
7781 The default terminal type (`dialup` in the example above) may depend on local preferences. `dialup` is the traditional default terminal type on dial-up lines so that users may customize their login scripts to notice when the terminal is `dialup` and automatically adjust their terminal type. However, the author finds it easier at his site to specify `vt102` as the default terminal type, since the users just use VT102 emulation on their remote systems.
7783 After you have made changes to `/etc/ttys`, you may send the `init` process a HUP signal to re-read the file. You can use the command
7789 to send the signal. If this is your first time setting up the system, you may want to wait until your modem(s) are properly configured and connected before signaling `init`.
7791 ##### 18.3.4.2.1 Locked-speed Config
7793 For a locked-speed configuration, your `ttys` entry needs to have a fixed-speed entry provided to `getty`. For a modem whose port speed is locked at 19.2 Kbps, the `ttys` entry might look like this:
7797 ttyd0 "/usr/libexec/getty std.19200" dialup on
7799 If your modem is locked at a different data rate, substitute the appropriate value for `std.`***speed****** instead of `std.19200`. Make sure that you use a valid type listed in `/etc/gettytab`.
7801 ##### 18.3.4.2.2 Matching-speed Config
7803 In a matching-speed configuration, your `ttys` entry needs to reference the appropriate beginning ***auto-baud*** (sic) entry in `/etc/gettytab`. For example, if you added the above suggested entry for a matching-speed modem that starts at 19.2 Kbps (the `gettytab` entry containing the `V19200` starting point), your `ttys` entry might look like this:
7807 ttyd0 "/usr/libexec/getty V19200" dialup on
7809 #### 18.3.4.3 `/etc/rc.serial`
7811 High-speed modems, like V.32, V.32bis, and V.34 modems, need to use hardware (`RTS/CTS`) flow control. You can add `stty` commands to `/etc/rc.serial` to set the hardware flow control flag in the DragonFly kernel for the modem ports.
7813 For example to set the `termios` flag `crtscts` on serial port #1's (`COM2`) dial-in and dial-out initialization devices, the following lines could be added to `/etc/rc.serial`:
7817 # Serial port initial configuration
7819 stty -f /dev/ttyid1 crtscts
7821 stty -f /dev/cuaia1 crtscts
7823 ### 18.3.5 Modem Settings
7825 If you have a modem whose parameters may be permanently set in non-volatile RAM, you will need to use a terminal program (such as Telix under MS-DOS® or `tip` under DragonFly) to set the parameters. Connect to the modem using the same communications speed as the initial speed `getty` will use and configure the modem's non-volatile RAM to match these requirements:
7827 * CD asserted when connected
7829 * DTR asserted for operation; dropping DTR hangs up line and resets modem
7831 * CTS transmitted data flow control
7833 * Disable XON/XOFF flow control
7835 * RTS received data flow control
7837 * Quiet mode (no result codes)
7841 Please read the documentation for your modem to find out what commands and/or DIP switch settings you need to give it.
7843 For example, to set the above parameters on a U.S. Robotics® Sportster® 14,400 external modem, one could give these commands to the modem:
7849 AT&C1&D2&H1&I0&R2&W
7851 You might also want to take this opportunity to adjust other settings in the modem, such as whether it will use V.42bis and/or MNP5 compression.
7853 The U.S. Robotics Sportster 14,400 external modem also has some DIP switches that need to be set; for other modems, perhaps you can use these settings as an example:
7855 * Switch 1: UP -- DTR Normal
7857 * Switch 2: N/A (Verbal Result Codes/Numeric Result Codes)
7859 * Switch 3: UP -- Suppress Result Codes
7861 * Switch 4: DOWN -- No echo, offline commands
7863 * Switch 5: UP -- Auto Answer
7865 * Switch 6: UP -- Carrier Detect Normal
7867 * Switch 7: UP -- Load NVRAM Defaults
7869 * Switch 8: N/A (Smart Mode/Dumb Mode)
7871 Result codes should be disabled/suppressed for dial-up modems to avoid problems that can occur if `getty` mistakenly gives a login: prompt to a modem that is in command mode and the modem echoes the command or returns a result code. This sequence can result in a extended, silly conversation between `getty` and the modem.
7873 #### 18.3.5.1 Locked-speed Config
7875 For a locked-speed configuration, you will need to configure the modem to maintain a constant modem-to-computer data rate independent of the communications rate. On a U.S. Robotics Sportster 14,400 external modem, these commands will lock the modem-to-computer data rate at the speed used to issue the commands:
7883 #### 18.3.5.2 Matching-speed Config
7885 For a variable-speed configuration, you will need to configure your modem to adjust its serial port data rate to match the incoming call rate. On a U.S. Robotics Sportster 14,400 external modem, these commands will lock the modem's error-corrected data rate to the speed used to issue the commands, but allow the serial port rate to vary for non-error-corrected connections:
7892 #### 18.3.5.3 Checking the Modem's Configuration
7894 Most high-speed modems provide commands to view the modem's current operating parameters in a somewhat human-readable fashion. On the U.S. Robotics Sportster 14,400 external modems, the command `ATI5` displays the settings that are stored in the non-volatile RAM. To see the true operating parameters of the modem (as influenced by the modem's DIP switch settings), use the commands `ATZ` and then `ATI4`.
7896 If you have a different brand of modem, check your modem's manual to see how to double-check your modem's configuration parameters.
7898 ### 18.3.6 Troubleshooting
7900 Here are a few steps you can follow to check out the dial-up modem on your system.
7902 #### 18.3.6.1 Checking Out the DragonFly System
7904 Hook up your modem to your DragonFly system, boot the system, and, if your modem has status indication lights, watch to see whether the modem's DTR indicator lights when the login: prompt appears on the system's console -- if it lights up, that should mean that DragonFly has started a `getty` process on the appropriate communications port and is waiting for the modem to accept a call.
7906 If the DTR indicator does not light, login to the DragonFly system through the console and issue a `ps ax` to see if DragonFly is trying to run a `getty` process on the correct port. You should see lines like these among the processes displayed:
7910 114 ?? I 0:00.10 /usr/libexec/getty V19200 ttyd0
7912 115 ?? I 0:00.10 /usr/libexec/getty V19200 ttyd1
7914 If you see something different, like this:
7918 114 d0 I 0:00.10 /usr/libexec/getty V19200 ttyd0
7920 and the modem has not accepted a call yet, this means that `getty` has completed its open on the communications port. This could indicate a problem with the cabling or a mis-configured modem, because `getty` should not be able to open the communications port until CD (carrier detect) has been asserted by the modem.
7922 If you do not see any `getty` processes waiting to open the desired `ttyd`***N****** port, double-check your entries in `/etc/ttys` to see if there are any mistakes there. Also, check the log file `/var/log/messages` to see if there are any log messages from `init` or `getty` regarding any problems. If there are any messages, triple-check the configuration files `/etc/ttys` and `/etc/gettytab`, as well as the appropriate device special files `/dev/ttydN`, for any mistakes, missing entries, or missing device special files.
7924 #### 18.3.6.2 Try Dialing In
7926 Try dialing into the system; be sure to use 8 bits, no parity, and 1 stop bit on the remote system. If you do not get a prompt right away, or get garbage, try pressing Enter about once per second. If you still do not see a login: prompt after a while, try sending a `BREAK`. If you are using a high-speed modem to do the dialing, try dialing again after locking the dialing modem's interface speed (via `AT&B1` on a U.S. Robotics Sportster modem, for example).
7928 If you dial but the modem on the DragonFly system will not answer, make sure that the modem is configured to answer the phone when DTR is asserted. If the modem seems to be configured correctly, verify that the DTR line is asserted by checking the modem's indicator lights (if it has any).
7930 If you have gone over everything several times and it still does not work, take a break and come back to it later. If it still does not work, perhaps you can send an electronic mail message to the [DragonFly User related mailing list](http://leaf.dragonflybsd.org/mailarchive/) describing your modem and your problem, and the good folks on the list will try to help.
7933 ## 18.4 Dial-out Service
7935 The following are tips for getting your host to be able to connect over the modem to another computer. This is appropriate for establishing a terminal session with a remote host.
7937 This is useful to log onto a BBS.
7939 This kind of connection can be extremely helpful to get a file on the Internet if you have problems with PPP. If you need to FTP something and PPP is broken, use the terminal session to FTP it. Then use zmodem to transfer it to your machine.
7941 ### 18.4.1 My Stock Hayes Modem Is Not Supported, What Can I Do?
7943 Actually, the manual page for `tip` is out of date. There is a generic Hayes dialer already built in. Just use `at=hayes` in your `/etc/remote` file.
7945 The Hayes driver is not smart enough to recognize some of the advanced features of newer modems--messages like `BUSY`, `NO DIALTONE`, or `CONNECT 115200` will just confuse it. You should turn those messages off when you use `tip` (using `ATX0&W`).
7947 Also, the dial timeout for `tip` is 60 seconds. Your modem should use something less, or else tip will think there is a communication problem. Try `ATS7=45&W`.
7949 **Note:** As shipped, `tip` does not yet support Hayes modems fully. The solution is to edit the file `tipconf.h` in the directory `/usr/src/usr.bin/tip/tip`. Obviously you need the source distribution to do this.
7951 Edit the line `#define HAYES 0` to `#define HAYES 1`. Then `make` and `make install`. Everything works nicely after that.
7953 ### 18.4.2 How Am I Expected to Enter These AT Commands?
7955 Make what is called a ***direct*** entry in your `/etc/remote` file. For example, if your modem is hooked up to the first serial port, `/dev/cuaa0`, then put in the following line:
7959 cuaa0:dv#/dev/cuaa0:br#19200:panone
7961 Use the highest bps rate your modem supports in the br capability. Then, type `tip cuaa0` and you will be connected to your modem.
7963 Or use `cu` as `root` with the following command:
7967 # cu -l`***line***` -s`***speed***`
7969 `***line***` is the serial port (e.g.`/dev/cuaa0`) and `***speed***` is the speed (e.g.`57600`). When you are done entering the AT commands hit **~.** to exit.
7971 ### 18.4.3 The `@` Sign for the pn Capability Does Not Work!
7973 The `@` sign in the phone number capability tells tip to look in `/etc/phones` for a phone number. But the `@` sign is also a special character in capability files like `/etc/remote`. Escape it with a backslash:
7979 ### 18.4.4 How Can I Dial a Phone Number on the Command Line?
7981 Put what is called a ***generic*** entry in your `/etc/remote` file. For example:
7985 tip115200|Dial any phone number at 115200 bps:\
7987 :dv#/dev/cuaa0:br#115200:athayes:pa=none:du:
7989 tip57600|Dial any phone number at 57600 bps:\
7991 :dv#/dev/cuaa0:br#57600:athayes:pa=none:du:
7993 Then you can do things like:
7997 # tip -115200 5551234
7999 If you prefer `cu` over `tip`, use a generic `cu` entry:
8003 cu115200|Use cu to dial any number at 115200bps:\
8005 :dv#/dev/cuaa1:br#57600:athayes:pa=none:du:
8011 # cu 5551234 -s 115200
8013 ### 18.4.5 Do I Have to Type in the bps Rate Every Time I Do That?
8015 Put in an entry for `tip1200` or `cu1200`, but go ahead and use whatever bps rate is appropriate with the br capability. `tip` thinks a good default is 1200 bps which is why it looks for a `tip1200` entry. You do not have to use 1200 bps, though.
8017 ### 18.4.6 I Access a Number of Hosts Through a Terminal Server
8019 Rather than waiting until you are connected and typing `CONNECT <host>` each time, use tip's `cm` capability. For example, these entries in `/etc/remote`:
8023 pain|pain.deep13.com|Forrester's machine:\
8025 :cm#CONNECT pain\n:tcdeep13:
8027 muffin|muffin.deep13.com|Frank's machine:\
8029 :cm#CONNECT muffin\n:tcdeep13:
8031 deep13:Gizmonics Institute terminal server:\
8033 :dv#/dev/cuaa2:br#38400:athayes:du:pa=none:pn=5551234:
8035 will let you type `tip pain` or `tip muffin` to connect to the hosts pain or muffin, and `tip deep13` to get to the terminal server.
8037 ### 18.4.7 Can Tip Try More Than One Line for Each Site?
8039 This is often a problem where a university has several modem lines and several thousand students trying to use them.
8041 Make an entry for your university in `/etc/remote` and use `@` for the `pn` capability:
8051 :dv#/dev/cuaa3:br#9600:atcourier:du:pa=none:
8053 Then, list the phone numbers for the university in `/etc/phones`:
8057 big-university 5551111
8059 big-university 5551112
8061 big-university 5551113
8063 big-university 5551114
8065 `tip` will try each one in the listed order, then give up. If you want to keep retrying, run `tip` in a while loop.
8067 ### 18.4.8 Why Do I Have to Hit **Ctrl** + **P** Twice to Send **Ctrl** + **P** Once?
8069 **Ctrl** + **P** is the default ***force*** character, used to tell `tip` that the next character is literal data. You can set the force character to any other character with the `~s` escape, which means ***set a variable.***
8071 Type `~sforce=`***single-char****** followed by a newline. `***single-char***` is any single character. If you leave out `***single-char***`, then the force character is the nul character, which you can get by typing **Ctrl** + **2** or **Ctrl** + **Space** . A pretty good value for `***single-char***` is **Shift** + **Ctrl** + **6** , which is only used on some terminal servers.
8073 You can have the force character be whatever you want by specifying the following in your `$HOME/.tiprc` file:
8077 force=<single-char>
8079 ### 18.4.9 Suddenly Everything I Type Is in Upper Case??
8081 You must have pressed **Ctrl** + **A** , `tip`'s ***raise character,*** specially designed for people with broken caps-lock keys. Use `~s` as above and set the variable `raisechar` to something reasonable. In fact, you can set it to the same as the force character, if you never expect to use either of these features.
8083 Here is a sample .tiprc file perfect for **Emacs** users who need to type **Ctrl** + **2** and **Ctrl** + **A** a lot:
8091 The ^^ is **Shift** + **Ctrl** + **6** .
8093 ### 18.4.10 How Can I Do File Transfers with `tip`?
8095 If you are talking to another UNIX® system, you can send and receive files with `~p` (put) and `~t` (take). These commands run `cat` and `echo` on the remote system to accept and send files. The syntax is:
8097 `~p` local-file [remote-file]
8099 `~t` remote-file [local-file]
8101 There is no error checking, so you probably should use another protocol, like zmodem.
8103 ### 18.4.11 How Can I Run zmodem with `tip`?
8105 To receive files, start the sending program on the remote end. Then, type `~C rz` to begin receiving them locally.
8107 To send files, start the receiving program on the remote end. Then, type `~C sz `***files****** to send them to the remote system.
8111 ## 18.5 Setting Up the Serial Console
8113 ### 18.5.1 Introduction
8115 DragonFly has the ability to boot on a system with only a dumb terminal on a serial port as a console. Such a configuration should be useful for two classes of people: system administrators who wish to install DragonFly on machines that have no keyboard or monitor attached, and developers who want to debug the kernel or device drivers.
8117 As described in [boot.html Chapter 10], DragonFly employs a three stage bootstrap. The first two stages are in the boot block code which is stored at the beginning of the DragonFly slice on the boot disk. The boot block will then load and run the boot loader (`/boot/loader`) as the third stage code.
8119 In order to set up the serial console you must configure the boot block code, the boot loader code and the kernel.
8121 ### 18.5.2 Serial Console Configuration, Terse Version
8123 This section assumes that you are using the default setup, know how to connect serial ports and just want a fast overview of a serial console. If you encounter difficulty with these steps, please see the more extensive explaination of all the options and advanced settings in [serialconsole-setup.html#SERIALCONSOLE-HOWTO Section 18.5.3].
8125 1. Connect the serial port. The serial console will be on COM1.
8127 1. `echo -h > /boot.config` to enable the serial console for the boot loader and kernel.
8129 1. Edit `/etc/ttys` and change `off` to `on` for the `ttyd0` entry. This enables a login prompt on the serial console, which mirrors how video consoles are typically setup.
8131 1. `shutdown -r now` will reboot the system with the serial console.
8133 ### 18.5.3 Serial Console Configuration
8135 1. Prepare a serial cable.
8137 You will need either a null-modem cable or a standard serial cable and a null-modem adapter. See [ Section 18.1.2](serial.html#SERIAL-CABLES-PORTS) for a discussion on serial cables.
8139 1. Unplug your keyboard.
8141 Most PC systems probe for the keyboard during the Power-On Self-Test (POST) and will generate an error if the keyboard is not detected. Some machines complain loudly about the lack of a keyboard and will not continue to boot until it is plugged in.
8143 If your computer complains about the error, but boots anyway, then you do not have to do anything special. (Some machines with Phoenix BIOS installed merely say ***`Keyboard failed`*** and continue to boot normally.)
8145 If your computer refuses to boot without a keyboard attached then you will have to configure the BIOS so that it ignores this error (if it can). Consult your motherboard's manual for details on how to do this.
8147 **Tip:** Setting the keyboard to ***Not installed*** in the BIOS setup does ***not*** mean that you will not be able to use your keyboard. All this does is tell the BIOS not to probe for a keyboard at power-on, so it will not complain if the keyboard is not plugged in. You can leave the keyboard plugged in even with this flag set to ***Not installed*** and the keyboard will still work.
8149 **Note:** If your system has a PS/2® mouse, chances are very good that you may have to unplug your mouse as well as your keyboard. This is because PS/2 mice share some hardware with the keyboard and leaving the mouse plugged in can fool the keyboard probe into thinking the keyboard is still there. In general, this is not a problem since the mouse is not much good without the keyboard anyway.
8151 1. Plug a dumb terminal into `COM1` (`sio0`).
8153 If you do not have a dumb terminal, you can use an old PC/XT with a modem program, or the serial port on another UNIX® box. If you do not have a `COM1` (`sio0`), get one. At this time, there is no way to select a port other than `COM1` for the boot blocks without recompiling the boot blocks. If you are already using `COM1` for another device, you will have to temporarily remove that device and install a new boot block and kernel once you get DragonFly up and running. (It is assumed that `COM1` will be available on a file/compute/terminal server anyway; if you really need `COM1` for something else (and you cannot switch that something else to `COM2` (`sio1`)), then you probably should not even be bothering with all this in the first place.)
8155 1. Make sure the configuration file of your kernel has appropriate flags set for `COM1` (`sio0`).
8159 `0x10`:: Enables console support for this unit. The other console flags are ignored unless this is set. Currently, at most one unit can have console support; the first one (in config file order) with this flag set is preferred. This option alone will not make the serial port the console. Set the following flag or use the `-h` option described below, together with this flag.`0x20`:: Forces this unit to be the console (unless there is another higher priority console), regardless of the `-h` option discussed below. This flag replaces the `COMCONSOLE` option in DragonFly versions 2.`***X***`. The flag `0x20` must be used together with the `0x10` flag.`0x40`:: Reserves this unit (in conjunction with `0x10`) and makes the unit unavailable for normal access. You should not set this flag to the serial port unit which you want to use as the serial console. This reserves this port for "low-level IO", i.e. kernel debugging.`0x80`:: This port will be used for remote kernel debugging.
8165 device sio0 at isa? port IO_COM1 flags 0x10 irq 4
8169 See the [sio(4)](http://leaf.dragonflybsd.org/cgi/web-man?command#sio§ion4) manual page for more details.
8171 If the flags were not set, you need to run UserConfig (on a different console) or recompile the kernel.
8173 1. Create `boot.config` in the root directory of the `a` partition on the boot drive.
8175 This file will instruct the boot block code how you would like to boot the system. In order to activate the serial console, you need one or more of the following options--if you want multiple options, include them all on the same line:
8177 `-h`:: Toggles internal and serial consoles. You can use this to switch console devices. For instance, if you boot from the internal (video) console, you can use `-h` to direct the boot loader and the kernel to use the serial port as its console device. Alternatively, if you boot from the serial port, you can use the `-h` to tell the boot loader and the kernel to use the video display as the console instead.`-D`:: Toggles single and dual console configurations. In the single configuration the console will be either the internal console (video display) or the serial port, depending on the state of the `-h` option above. In the dual console configuration, both the video display and the serial port will become the console at the same time, regardless of the state of the `-h` option. However, note that the dual console configuration takes effect only during the boot block is running. Once the boot loader gets control, the console specified by the `-h` option becomes the only console.`-P`:: Makes the boot block probe the keyboard. If no keyboard is found, the `-D` and `-h` options are automatically set.
8179 **Note:** Due to space constraints in the current version of the boot blocks, the `-P` option is capable of detecting extended keyboards only. Keyboards with less than 101 keys (and without F11 and F12 keys) may not be detected. Keyboards on some laptop computers may not be properly found because of this limitation. If this is the case with your system, you have to abandon using the `-P` option. Unfortunately there is no workaround for this problem.
8181 Use either the `-P` option to select the console automatically, or the `-h` option to activate the serial console.
8183 You may include other options described in [boot(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#boot§ion8) as well.
8185 The options, except for `-P`, will be passed to the boot loader (`/boot/loader`). The boot loader will determine which of the internal video or the serial port should become the console by examining the state of the `-h` option alone. This means that if you specify the `-D` option but not the `-h` option in `/boot.config`, you can use the serial port as the console only during the boot block; the boot loader will use the internal video display as the console.
8187 1. Boot the machine.
8189 When you start your DragonFly box, the boot blocks will echo the contents of `/boot.config` to the console. For example:
8199 The second line appears only if you put `-P` in `/boot.config` and indicates presence/absence of the keyboard. These messages go to either serial or internal console, or both, depending on the option in `/boot.config`.
8201 || Options || Message goes to ||
8203 || none || internal console ||
8205 || `-h` || serial console ||
8207 || `-D` || serial and internal consoles ||
8209 || `-Dh` || serial and internal consoles ||
8211 || `-P`, keyboard present || internal console ||
8213 || `-P`, keyboard absent || serial console ||
8215 After the above messages, there will be a small pause before the boot blocks continue loading the boot loader and before any further messages printed to the console. Under normal circumstances, you do not need to interrupt the boot blocks, but you may want to do so in order to make sure things are set up correctly.
8217 Hit any key, other than Enter, at the console to interrupt the boot process. The boot blocks will then prompt you for further action. You should now see something like:
8221 >> DragonFly/i386 BOOT
8223 Default: 0:ad(0,a)/boot/loader
8229 Verify the above message appears on either the serial or internal console or both, according to the options you put in `/boot.config`. If the message appears in the correct console, hit Enter to continue the boot process.
8231 If you want the serial console but you do not see the prompt on the serial terminal, something is wrong with your settings. In the meantime, you enter `-h` and hit Enter/Return (if possible) to tell the boot block (and then the boot loader and the kernel) to choose the serial port for the console. Once the system is up, go back and check what went wrong.
8233 After the boot loader is loaded and you are in the third stage of the boot process you can still switch between the internal console and the serial console by setting appropriate environment variables in the boot loader. See [serialconsole-setup.html#SERIALCONSOLE-LOADER Section 18.5.6].
8237 Here is the summary of various settings discussed in this section and the console eventually selected.
8239 #### 18.5.4.1 Case 1: You Set the Flags to 0x10 for `sio0`
8243 device sio0 at isa? port IO_COM1 flags 0x10 irq 4
8246 | Options in /boot.config | Console during boot blocks | Console during boot loader | Console in kernel
8247 nothing | internal | internal | internal
8248 `-h` | serial | serial | serial
8249 `-D` | serial and internal | internal | internal
8250 `-Dh` | serial and internal | serial | serial
8251 `-P`, keyboard present | internal | internal | internal
8252 `-P`, keyboard absent | serial and internal | serial | serial |
8256 #### 18.5.4.2 Case 2: You Set the Flags to 0x30 for sio0
8260 device sio0 at isa? port IO_COM1 flags 0x30 irq 4
8263 | Options in /boot.config | Console during boot blocks | Console during boot loader | Console in kernel
8264 nothing | internal | internal | serial
8265 `-h` | serial | serial | serial
8266 `-D` | serial and internal | internal | serial
8267 `-Dh` | serial and internal | serial | serial
8268 `-P`, keyboard present | internal | internal | serial
8269 `-P`, keyboard absent | serial and internal | serial | serial |
8273 ### 18.5.5 Tips for the Serial Console
8275 #### 18.5.5.1 Setting a Faster Serial Port Speed
8277 By default, the serial port settings are: 9600 baud, 8 bits, no parity, and 1 stop bit. If you wish to change the speed, you need to recompile at least the boot blocks. Add the following line to `/etc/make.conf` and compile new boot blocks:
8281 BOOT_COMCONSOLE_SPEED=19200
8283 If the serial console is configured in some other way than by booting with `-h`, or if the serial console used by the kernel is different from the one used by the boot blocks, then you must also add the following option to the kernel configuration file and compile a new kernel:
8287 options CONSPEED=19200
8289 #### 18.5.5.2 Using Serial Port Other Than `sio0` for the Console
8291 Using a port other than `sio0` as the console requires some recompiling. If you want to use another serial port for whatever reasons, recompile the boot blocks, the boot loader and the kernel as follows.
8293 1. Get the kernel source.
8295 1. Edit `/etc/make.conf` and set `BOOT_COMCONSOLE_PORT` to the address of the port you want to use (0x3F8, 0x2F8, 0x3E8 or 0x2E8). Only `sio0` through `sio3` (`COM1` through `COM4`) can be used; multiport serial cards will not work. No interrupt setting is needed.
8297 1. Create a custom kernel configuration file and add appropriate flags for the serial port you want to use. For example, if you want to make `sio1` (`COM2`) the console:
8301 device sio1 at isa? port IO_COM2 flags 0x10 irq 3
8309 device sio1 at isa? port IO_COM2 flags 0x30 irq 3
8313 The console flags for the other serial ports should not be set.
8315 1. Recompile and install the boot blocks and the boot loader:
8327 1. Rebuild and install the kernel.
8329 1. Write the boot blocks to the boot disk with [disklabel(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#disklabel§ion8) and boot from the new kernel.
8331 #### 18.5.5.3 Entering the DDB Debugger from the Serial Line
8333 If you wish to drop into the kernel debugger from the serial console (useful for remote diagnostics, but also dangerous if you generate a spurious BREAK on the serial port!) then you should compile your kernel with the following options:
8337 options BREAK_TO_DEBUGGER
8341 #### 18.5.5.4 Getting a Login Prompt on the Serial Console
8343 While this is not required, you may wish to get a ***login*** prompt over the serial line, now that you can see boot messages and can enter the kernel debugging session through the serial console. Here is how to do it.
8345 Open the file `/etc/ttys` with an editor and locate the lines:
8349 ttyd0 "/usr/libexec/getty std.9600" unknown off secure
8351 ttyd1 "/usr/libexec/getty std.9600" unknown off secure
8353 ttyd2 "/usr/libexec/getty std.9600" unknown off secure
8355 ttyd3 "/usr/libexec/getty std.9600" unknown off secure
8357 `ttyd0` through `ttyd3` corresponds to `COM1` through `COM4`. Change `off` to `on` for the desired port. If you have changed the speed of the serial port, you need to change `std.9600` to match the current setting, e.g. `std.19200`.
8359 You may also want to change the terminal type from `unknown` to the actual type of your serial terminal.
8361 After editing the file, you must `kill -HUP 1` to make this change take effect.
8363 ### 18.5.6 Changing Console from the Boot Loader
8365 Previous sections described how to set up the serial console by tweaking the boot block. This section shows that you can specify the console by entering some commands and environment variables in the boot loader. As the boot loader is invoked at the third stage of the boot process, after the boot block, the settings in the boot loader will override the settings in the boot block.
8367 #### 18.5.6.1 Setting Up the Serial Console
8369 You can easily specify the boot loader and the kernel to use the serial console by writing just one line in `/boot/loader.rc`:
8373 set console=comconsole
8375 This will take effect regardless of the settings in the boot block discussed in the previous section.
8377 You had better put the above line as the first line of `/boot/loader.rc` so as to see boot messages on the serial console as early as possible.
8379 Likewise, you can specify the internal console as:
8383 set console=vidconsole
8385 If you do not set the boot loader environment variable `console`, the boot loader, and subsequently the kernel, will use whichever console indicated by the `-h` option in the boot block.
8387 In versions 3.2 or later, you may specify the console in `/boot/loader.conf.local` or `/boot/loader.conf`, rather than in `/boot/loader.rc`. In this method your `/boot/loader.rc` should look like:
8391 include /boot/loader.4th
8395 Then, create `/boot/loader.conf.local` and put the following line there.
8407 **Note:** At the moment, the boot loader has no option equivalent to the `-P` option in the boot block, and there is no provision to automatically select the internal console and the serial console based on the presence of the keyboard.
8409 #### 18.5.6.2 Using a Serial Port Other Than `sio0` for the Console
8411 You need to recompile the boot loader to use a serial port other than `sio0` for the serial console. Follow the procedure described in [serialconsole-setup.html#SERIALCONSOLE-COM2 Section 18.5.5.2].
8415 The idea here is to allow people to set up dedicated servers that require no graphics hardware or attached keyboards. Unfortunately, while most systems will let you boot without a keyboard, there are quite a few that will not let you boot without a graphics adapter. Machines with AMI BIOSes can be configured to boot with no graphics adapter installed simply by changing the ***graphics adapter*** setting in the CMOS configuration to ***Not installed.***
8417 # Chapter 1 Introduction
8419 ***Restructured, reorganized, and parts rewritten by Jim Mock. ***
8423 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.
8425 After reading this chapter, you will know:
8427 * How DragonFly relates to other computer operating systems.
8429 * The history of the DragonFly Project.
8431 * The goals of the DragonFly Project.
8433 * The basics of the DragonFly open-source development model.
8435 * And of course: where the name ***DragonFly*** comes from.
8439 ## Welcome to DragonFly!
8441 DragonFly is a [[4.4BSD-Lite|http://en.wikipedia.org/wiki/Berkeley_Software_Distribution]] unix operating system for Intel (x86) and amd64 (x86_64) architectures.
8443 ### What Can DragonFly Do?
8445 <!-- Cutout of "features". This is outdated bullshit -->
8447 Work on BSD-flavor Unix systems running on PC compatible hardware started as a fork of the 4.4BSD-Lite release from Computer Systems Research Group (CSRG) at the University of California at Berkeley. One of the variants that became quite popular became known later as FreeBSD. Firefly BSD started out as a fork, and continuation of FreeBSD 4.8.
8449 Like all other modern PC compatible BSD variants, it carries on the distinguished tradition of BSD systems development. In addition to the fine work provided by CSRG, the DragonFly Project has put in many thousands of hours in fine tuning the system for maximum performance and reliability in real-life load situations.
8451 As many of the commercial giants struggle to field PC operating systems with such features, performance and reliability, DragonFly can offer them ***now***!
8452 For example the `Hammer` filesystem, which is the default filesystem in DragonFly BSD, is the most powerful and reliable filesystem available on any operating system.
8454 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.
8456 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:
8458 The robust TCP/IP networking built into DragonFly makes it an ideal platform for a variety of Internet services such as:
8461 * World Wide Web servers (standard or secure [SSL])
8462 * Firewalls and NAT (***IP masquerading***) gateways
8463 * Electronic Mail servers
8464 * USENET News or Bulletin Board Systems
8467 With DragonFly, you can install on almost any PC, from older 32 bit computers running 386 or Pentium chips, to modern 64 bit Intel Core or AMD X64 desktop CPUs, and even up to and including high end Xeon CPUs. All of these CPUs share a common ancestry, and instruction set, going back to the original Intel 80386 CPU which was the first fully 32-bit desktop CPU for "IBM PC compatible" computers.
8469 Here are some of the fields where people are using Dragonfly BSD, and the reasons that they find DragonFly BSD fits their needs:
8471 * ***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!
8473 * ***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.
8475 * ***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.
8477 * ***X Window workstation:*** DragonFly is a fine choice for an inexpensive X terminal solution, using the freely available X.org server. Unlike an X terminal, DragonFly allows many applications to be run locally if desired, thus relieving the burden on a central server. DragonFly can even boot ***diskless***, making individual workstations even cheaper and easier to administer.
8479 * ***Software Development:*** The basic DragonFly system comes with a full complement of development tools including the renowned GNU C/C++ compiler and debugger.
8481 DragonFly is available via anonymous FTP or GIT. Please see [Appendix A](mirrors.html) for more information about obtaining DragonFly.
8483 For more help on installing, see the appropriate sections of this handbook.
8487 ## About the DragonFly Project
8489 The following section provides some background information on the project, including a brief history, project goals, and the development model of the project.
8491 ### A Brief History of DragonFly
8493 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.
8495 ### DragonFly Project Goals
8497 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.
8499 ### The DragonFly Development Model
8501 ***Written by Justin Sherrill. ***
8503 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.
8505 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.
8507 ### The Current DragonFly Release
8509 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.
8511 ### DragonFly Origin
8513 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.
8515 ## Updating the System
8517 ### Supported methods
8519 The only **supported** method of upgrading DragonFly BSD is by building from source code. <br><br>
8520 Supported upgrade process includes going from the *previous release* to *latest release*.<br>
8522 For example, in our actual case, only the upgrade process involving <u>2.10.x up to 3.0.x</u> would be supported.
8524 ### Getting the source code
8526 There is a Makefile in /usr which will ease the task of retrieving the source tree; it needs to be run as root:
8532 And that will effectively checkout the source tree on `/usr/src` and switch to master branch. For stable branch you need to check it out with the following command (remember to replace the *DragonFly_RELEASE_3_0* with the appropriate branch name for the release needed).
8535 % git checkout DragonFly_RELEASE_3_0
8537 To see the available remote branches:
8543 The leading edge (development trunk) version of the system will be the "master".
8545 ### Build and upgrade process
8547 Build process requires some time to build all the userland programs and the DragonFly BSD kernel. Once built, next step is to install everything and make the upgrade target. No configuration files in */etc* are changed by this process. More details can be found in **[build(7)](http://leaf.dragonflybsd.org/cgi/web-man?command=build§ion=ANY)** manpage.
8552 % make installkernel
8557 **Note:** You may use a concurrent build if you have a SMP (a machine with several cores or CPUs). You may specify *-j x* parameter to make where x is the number of CPUs + 1. <br>
8558 If you run DragonFly 2.12 or higher the kernel will auto-detect the number of CPUs your computer has and activate them all if possible. To find out how many CPUs your computer has:
8564 An explanation of each step follows.
8566 * <u>*make buildworld*</u> : This command builds all userland programs and it is the most time-consuming step.<br>
8567 Some programs may be discarded from the build process.<br>
8568 For more details check **[make.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=make.conf§ion=ANY)** manpage.
8570 * <u>*make buildkernel*</u> : This builds the kernel using the config file by default for your architecture. You may also specify a different kernel configuration file using KERNCONF=configfile. More details on **[make.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=make.conf§ion=ANY)** manpage.
8572 * <u>*make installkernel*</u> This installs the kernel using the config file for your architecture or KERNCONF=file can be used to specify which one to install.
8574 * <u>*make installworld*</u> : This copies all the files built in the buildworld step (i.e. everything that is not the kernel) to the proper places in the filesystem.
8576 * <u>*make upgrade*</u> : This cleans out any files made unnecessary by this upgrade.
8578 * (reboot) : Reboot the computer to load the new kernel and use the new files installed as part of this process.
8580 If your computer fails to boot the new kernel, you can always select 'Boot DragonFly using kernel.old' in the loader menu, so that the old kernel is loaded instead of the new one.
8582 Additional upgrading instructions can be found in */usr/src/UPDATING* in the source tree. Online it can be found **[here](http://gitweb.dragonflybsd.org/dragonfly.git/blob_plain/master:/UPDATING)**
8584 # DragonFly BSD Quick Start
8586 This QuickStart is part of the [[NewHandbook|/docs/newhandbook/]].
8588 This document describes the DragonFly environment one will find on a newly installed system. While you are getting started please pay careful attention to the version or level of DragonFly that the documentation was written for. Some documentation on this site may be out of date. Watch for the marker `(obsolete)` on items that are out of date or need updating.
8591 ## Some Unix and BSD Fundamentals
8593 If you have used another Unix flavor, another BSD or Linux before, you may need to spend some time learning basic subjects. If you have never used any flavor of Unix, BSD or otherwise, and have only used Windows before, please be prepared for a lengthy period of learning.
8595 If you already know your way around a Unix filesystem, and already know what the `/etc` folder is, how to use `vi` or `vim` to edit a file, how to use a shell like `tcsh` or `bash`, how to configure that shell, or change what shell you're using, how `su` and `sudo` work, and what a `root` account is, then you may get a lot farther in using any BSD variant (like Dragonfly BSD) then the rest of this page may be enough to orient you to your surroundings.
8597 You should understand everything in the [[Unix Basics|/docs/newhandbook/UnixBasics/]] section before you proceed with trying to use your new system.
8599 ## Disk layout of a New Dragonfly BSD System using the HAMMER filesystem
8601 If you chose to install on the HAMMER file system during installation you will be left with a system with the following disk configuration:
8604 Filesystem Size Used Avail Capacity Mounted on
8605 ROOT 288G 12G 276G 4% /
8606 devfs 1.0K 1.0K 0B 100% /dev
8607 /dev/serno/9VMBWDM1.s1a 756M 138M 558M 20% /boot
8608 /pfs/@@-1:00001 288G 12G 276G 4% /var
8609 /pfs/@@-1:00002 288G 12G 276G 4% /tmp
8610 /pfs/@@-1:00003 288G 12G 276G 4% /usr
8611 /pfs/@@-1:00004 288G 12G 276G 4% /home
8612 /pfs/@@-1:00005 288G 12G 276G 4% /usr/obj
8613 /pfs/@@-1:00006 288G 12G 276G 4% /var/crash
8614 /pfs/@@-1:00007 288G 12G 276G 4% /var/tmp
8615 procfs 4.0K 4.0K 0B 100% /proc
8619 * `/dev/serno/9VMBWDM1` is the hard disk specified with serial number,
8620 * `/dev/serno/9VMBWDM1.s1` is the first slice on the hard disk.
8622 The disklabel looks at follows
8624 # disklabel /dev/serno/9VMBWDM1.s1
8626 # /dev/serno/9VMBWDM1.s1:
8628 # Informational fields calculated from the above
8629 # All byte equivalent offsets must be aligned
8631 # boot space: 1044992 bytes
8632 # data space: 312567643 blocks # 305241.84 MB (320069266944 bytes)
8634 # NOTE: If the partition data base looks odd it may be
8635 # physically aligned instead of slice-aligned
8637 diskid: e67030af-d2af-11df-b588-01138fad54f5
8639 boot2 data base: 0x000000001000
8640 partitions data base: 0x000000100200
8641 partitions data stop: 0x004a85ad7000
8642 backup label: 0x004a85ad7000
8643 total size: 0x004a85ad8200 # 305242.84 MB
8645 display block size: 1024 # for partition display only
8648 # size offset fstype fsuuid
8649 a: 786432 0 4.2BSD # 768.000MB
8650 b: 8388608 786432 swap # 8192.000MB
8651 d: 303392600 9175040 HAMMER # 296281.836MB
8652 a-stor_uuid: eb1c8aac-d2af-11df-b588-01138fad54f5
8653 b-stor_uuid: eb1c8aec-d2af-11df-b588-01138fad54f5
8654 d-stor_uuid: eb1c8b21-d2af-11df-b588-01138fad54f5
8656 The slice has 3 partitions:
8660 * `d` - for `/`, a HAMMER file system labeled ROOT
8662 When you create a HAMMER file system you must give it a label, here the installer labeled it as "ROOT" and mounted it as
8664 ROOT 288G 12G 276G 4% /
8666 A PFS is a Pseudo File System inside a HAMMER file system. The HAMMER file system in which the PFSes are created is referred to as the root file system. You should not confuse the "root" file system with the Label "ROOT", the label can be anything. It is just that the installer labeled it as ROOT because it is mounted as `/`.
8668 Now inside the ROOT HAMMER file system you find the installed created 7 PFSes from the `df -h` output above, let us see how they are mounted in `/etc/fstab`:
8672 # Device Mountpoint FStype Options Dump Pass#
8673 /dev/serno/9VMBWDM1.s1a /boot ufs rw 1 1
8674 /dev/serno/9VMBWDM1.s1b none swap sw 0 0
8675 /dev/serno/9VMBWDM1.s1d / hammer rw 1 1
8676 /pfs/var /var null rw 0 0
8677 /pfs/tmp /tmp null rw 0 0
8678 /pfs/usr /usr null rw 0 0
8679 /pfs/home /home null rw 0 0
8680 /pfs/usr.obj /usr/obj null rw 0 0
8681 /pfs/var.crash /var/crash null rw 0 0
8682 /pfs/var.tmp /var/tmp null rw 0 0
8683 proc /proc procfs rw 0 0
8685 The PFSes are mounted using a NULL mount because they are also HAMMER file systems. You can read more on NULL mounts here [mount_null(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=mount_null§ion=8).
8687 You don't need to specify a size for the PFSes like you do for logical volumes inside a volume group for LVM. All the free space in the root HAMMER file system is available to all the PFSs. That is the reason in the `df -h` output above you saw free space is same for all PFSes and the root HAMMER file system.
8689 Now if you look in `/var`
8693 account backups caps cron empty log msgs run spool yp at
8694 cache crash db games lib mail preserve rwho tmp
8696 you will find the above directories.
8698 If you look at the status of one of the PFSes, e.g. `/usr` you will see `/var/hammer` is the default snapshot directory.
8700 # hammer pfs-status /usr/
8702 sync-beg-tid=0x0000000000000001
8703 sync-end-tid=0x0000000117ac6270
8704 shared-uuid=f33e318e-d2af-11df-b588-01138fad54f5
8705 unique-uuid=f33e31cb-d2af-11df-b588-01138fad54f5
8708 operating as a MASTER
8709 snapshots directory defaults to /var/hammer/<pfs>
8712 There is no "hammer" directory in `/var` now. That is because no snapshots are yet taken. You can verify this by checking the snapshots available for `/usr`
8714 # hammer snapls /usr
8715 Snapshots on /usr PFS #3
8716 Transaction ID Timestamp Note
8718 Snapshots will appear automatically each night as the system performs housekeeping on the Hammer filesystem. For a new volume, an immediate snapshot can be taken by running the command 'hammer cleanup'. Among other activites, it will take a snapshot of the filesystem.
8720 # sudo hammer cleanup
8721 cleanup / - HAMMER UPGRADE: Creating snapshots
8722 Creating snapshots in /var/hammer/root
8723 handle PFS #0 using /var/hammer/root
8729 cleanup /var - HAMMER UPGRADE: Creating snapshots
8731 cleanup /tmp - HAMMER UPGRADE: Creating snapshots
8733 cleanup /usr - HAMMER UPGRADE: Creating snapshots
8735 cleanup /home - HAMMER UPGRADE: Creating snapshots
8737 cleanup /usr/obj - HAMMER UPGRADE: Creating snapshots
8739 cleanup /var/crash - HAMMER UPGRADE: Creating snapshots
8741 cleanup /var/tmp - HAMMER UPGRADE: Creating snapshots
8743 cleanup /var/isos - HAMMER UPGRADE: Creating snapshots
8746 No snapshots were taken for `/tmp`, `/usr/obj` and `/var/tmp`. This is because the PFSes are flagged as `nohistory`. HAMMER tracks history for all files in a PFS, naturally this consumes disk space until the history is pruned. To prevent that temporary files on the mentioned PFSes (e.g., object files, crash dumps) consume disk space, the PFSes are marked as `nohistory`.
8748 In `/var` will be a new directory called *hammer* with the following sub directories
8753 drwxr-xr-x 1 root wheel 0 Oct 13 11:51 home
8754 drwxr-xr-x 1 root wheel 0 Oct 13 11:42 root
8755 drwxr-xr-x 1 root wheel 0 Oct 13 11:43 tmp
8756 drwxr-xr-x 1 root wheel 0 Oct 13 11:51 usr
8757 drwxr-xr-x 1 root wheel 0 Oct 13 11:54 var
8759 Well let us look inside `/var/hammer/usr`
8764 drwxr-xr-x 1 root wheel 0 Oct 13 11:54 obj
8765 lrwxr-xr-x 1 root wheel 25 Oct 13 11:43 snap-20101013-1143 -> /usr/@@0x0000000117ac6cb0
8767 We have a symlink pointing to the snapshot transaction ID shown below.
8769 # hammer snapls /usr
8770 Snapshots on /usr PFS #3
8771 Transaction ID Timestamp Note
8772 0x0000000117ac6cb0 2010-10-13 11:43:04 IST -
8775 You can read more about snapshots, prune, reblance, reblock, recopy etc from [hammer(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=hammer§ion=8) especially look under the heading "cleanup [filesystem ...]"
8777 You can learn more about PFS mirroring [here](http://www.dragonflybsd.org/docs/how_to_implement_hammer_pseudo_file_system__40___pfs___41___slave_mirroring_from_pfs_master/)
8779 In order to correctly map hard disk sernos to device names you can use the 'devattr' command.
8782 # devattr -d "ad*" -p serno
8800 Or if your disks are 'da', just change it as appropiate.
8802 ## Configuring and Starting the SSH Server
8804 Described in detail [[here|/docs/newhandbook/sshserver/]]
8806 ## Software/Programs and Configuration Files Location
8808 DragonFly default installation contains the base software/programs from the DragonFly project itself and few other software from other sources.
8810 The base system binary software programs are located in the folders
8815 The configuration files for the base system can be found in `/etc`. There is also `/usr/local/etc` which is used by third-party programs.
8817 There are several different ways to install software and which version you use depends on which DragonFly BSD version you have. You can compile things from source code, or you can use binary packages.
8819 ## Installing Third-party Software
8821 Have a look at the [[dports howto|/docs/howtos/HowToDPorts/]] for an in-depth description about dealing with packaging systems. Note that DragonFly BSD has several older package managers (like `pkgin`), but that the most modern binary package installation system as of 2014, is `pkg`.
8825 Read [[dports howto|/docs/howtos/HowToDPorts/]] then for some errata, read [[this|http://lists.dragonflybsd.org/pipermail/users/2013-November/090339.html]].
8827 You can look at the help and the man page for the pkg tool like this:
8831 Example: Read man page for pkg-install
8835 ### Installing an X.org desktop X11 environment and XFCE desktop
8837 If it's already on your system run X by typing `startx`. If it's not, be sure to check your dports configuration is finished, then install it using `pkg install xorg-7.7 xfce4-desktop`. This will install the core X.org X11 server, and an XFCE based desktop environment.
8840 Slightly out of date instructions on installing a GUI (X desktop) environment are in the [new handbook](http://www.dragonflybsd.org/docs/newhandbook/X/).
8844 ***Rewritten by Chris Shumway. ***
8849 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.
8851 After reading this chapter, you will know:
8853 * How to use the ***virtual consoles*** of DragonFly.
8855 * How UNIX file permissions work along with understanding file flags in DragonFly.
8857 * The default DragonFly file system layout.
8859 * The DragonFly disk organization.
8861 * How to mount and unmount file systems.
8863 * What processes, daemons, and signals are.
8865 * What a shell is, and how to change your default login environment.
8867 * How to use basic text editors.
8869 * What devices and device nodes are.
8871 * What binary format is used under DragonFly.
8873 * How to read manual pages for more information.
8875 ## Virtual Consoles and Terminals
8877 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.
8879 <!-- XXX: also mention vesa.ko and other modes for the vt, but maybe somewhere else -->
8883 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:
8885 Additional ABI support:.
8887 Local package initialization:.
8888 Additional TCP options:.
8890 Wed Feb 18 17:53:48 GMT 2009
8892 DragonFly/i386 (Amnesiac) (ttyv0)
8896 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:
8898 DragonFly/i386 (Amnesiac) (ttyv0)
8900 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:
8904 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.
8906 ### Logging into DragonFly
8908 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.
8910 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:
8914 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>:
8920 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.
8922 ### Multiple Consoles
8924 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.
8926 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.
8928 ### The /etc/ttys File
8930 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.
8932 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`:
8935 # name getty type status comments
8937 ttyv0 "/usr/libexec/getty Pc" cons25 on secure
8939 ttyv1 "/usr/libexec/getty Pc" cons25 on secure
8940 ttyv2 "/usr/libexec/getty Pc" cons25 on secure
8941 ttyv3 "/usr/libexec/getty Pc" cons25 on secure
8942 ttyv4 "/usr/libexec/getty Pc" cons25 on secure
8943 ttyv5 "/usr/libexec/getty Pc" cons25 on secure
8944 ttyv6 "/usr/libexec/getty Pc" cons25 on secure
8945 ttyv7 "/usr/libexec/getty Pc" cons25 on secure
8946 ttyv8 "/usr/pkg/xorg/bin/xdm -nodaemon" xterm off secure
8948 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.
8950 ### Single User Mode Console
8952 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`:
8956 # name getty type status comments
8958 # If console is marked "insecure", then init will ask for the root password
8959 # when going to single-user mode.
8960 console none unknown off secure
8962 **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.
8967 <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.
8968 [ (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.
8969 [ (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. |
8975 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.
8977 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:
8980 |<tablestyle="width:100%"> Value | Permission | Directory Listing
8981 <tablestyle="width:100%"> 0 | No read, no write, no execute | `---`
8982 1 | No read, no write, execute | `--x`
8983 2 | No read, write, no execute | `-w-`
8984 3 | No read, write, execute | `-wx`
8985 4 | Read, no write, no execute | `r--`
8986 5 | Read, no write, execute | `r-x`
8987 6 | Read, write, no execute | `rw-`
8988 7 | Read, write, execute | `rwx` |
8992 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:
8996 -rw-r--r-- 1 root wheel 512 Sep 5 12:31 myfile
8997 -rw-r--r-- 1 root wheel 512 Sep 5 12:31 otherfile
8998 -rw-r--r-- 1 root wheel 7680 Sep 5 12:31 email.txt
9001 Here is how the first column of `ls -l` is broken up:
9005 <!-- XXX: Check all these http:// links to see if they are broken -->
9007 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.
9009 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.
9011 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).
9013 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.
9015 ### Symbolic Permissions
9017 ***Contributed by Tom Rhodes.***
9019 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:
9022 <tablestyle="width:100%"> Option | Letter | Represents
9023 <tablestyle="width:100%"> (who) | u | User
9024 (who) | g | Group owner
9026 (who) | a | All (***world***)
9027 (action) | + | Adding permissions
9028 (action) | - | Removing permissions
9029 (action) | = | Explicitly set permissions
9030 (permissions) | r | Read
9031 (permissions) | w | Write
9032 (permissions) | x | Execute
9033 (permissions) | t | Sticky bit
9034 (permissions) | s | Set UID or GID |
9038 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`:
9044 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:
9048 % chmod go-w,a+x FILE
9050 ### DragonFly File Flags
9052 ***Contributed by Tom Rhodes.***
9054 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:
9058 # chflags sunlink file1
9060 And to disable the system undeletable flag, simply issue the previous command with ***no*** in front of the `sunlink`. Observe:
9064 # chflags nosunlink file1
9066 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:
9072 The output should look like the following:
9076 -rw-r--r-- 1 trhodes trhodes sunlnk 0 Mar 1 05:54 file1
9078 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.
9080 ## Directory Structure
9082 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.
9084 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).
9086 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.
9089 <tablestyle="width:100%">Directory | Description
9090 <tablestyle="width:100%"> `/` | Root directory of the file system.
9091 `/bin/` | User utilities fundamental to both single-user and multi-user environments.
9092 `/boot/` | Programs and configuration files used during operating system bootstrap.
9093 `/boot/defaults/` | Default bootstrapping configuration files; see [loader.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=loader.conf§ion5).
9094 `/dev/` | Device nodes; see [intro(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=intro§ion4).
9095 `/etc/` | System configuration files and scripts.
9096 `/etc/defaults/` | Default system configuration files; see [rc(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rc§ion8).
9097 `/etc/mail/` | Configuration files for mail transport agents such as [sendmail(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=sendmail§ion8).
9098 `/etc/namedb/` | `named` configuration files; see [named(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=named§ion8).
9099 `/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).
9100 `/etc/ppp/` | `ppp` configuration files; see [ppp(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=ppp§ion8).
9101 `/mnt/` | Empty directory commonly used by system administrators as a temporary mount point.
9102 `/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).
9103 `/root/` | Home directory for the `root` account.
9104 `/sbin/` | System programs and administration utilities fundamental to both single-user and multi-user environments.
9105 `/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).
9106 `/usr/` | The majority of user utilities and applications.
9107 `/usr/bin/` | Common utilities, programming tools, and applications.
9108 `/usr/include/` | Standard C include files.
9109 `/usr/lib/` | Archive libraries.
9110 `/usr/libdata/` | Miscellaneous utility data files.
9111 `/usr/libexec/` | System daemons & system utilities (executed by other programs).
9112 `/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`.
9113 `/usr/obj/` | Architecture-specific target tree produced by building the `/usr/src` tree.
9114 `/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`.
9115 `/usr/pkg/xorg/` | Xorg distribution executables, libraries, etc (optional).
9116 `/usr/pkgsrc` | The pkgsrc tree for installing packages (optional).
9117 `/usr/sbin/` | System daemons & system utilities (executed by users).
9118 `/usr/share/` | Architecture-independent files.
9119 `/usr/src/` | BSD and/or local source files.
9120 `/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).
9121 `/var/log/` | Miscellaneous system log files.
9122 `/var/mail/` | User mailbox files.
9123 `/var/spool/` | Miscellaneous printer and mail system spooling directories.
9124 `/var/tmp/` | Temporary files. The files are usually preserved across a system reboot, unless `/var` is a memory-based file system.
9125 `/var/yp` | NIS maps. |
9129 ## Disk Organization
9131 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.
9133 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.
9135 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`.
9137 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.
9139 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 `\`.
9141 DragonFly does not use drive letters, or other drive names in the path. You would not write `c:/foo/bar/readme.txt` on DragonFly.
9143 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.
9145 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`).
9147 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:
9151 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:
9155 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.
9157 If `B` had been mounted on `A2` then the diagram would look like this:
9161 and the paths would be `/A2/B1` and `/A2/B2` respectively.
9163 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:
9167 Or `C` could be mounted directly on to the `A` file system, under the `A1` directory:
9171 If you are familiar with MS-DOS, this is similar, although not identical, to the `join` command.
9173 ## Choosing File System Layout
9175 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.
9177 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.
9179 **Benefits of Multiple File Systems**
9181 * 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.
9183 * 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.
9185 * 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.
9187 **Benefit of a Single File System**
9189 * 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.
9190 <!-- XXX: what about hammer? -->
9192 ## Disk Slices, Partitions and local UNIX file systems
9194 Here we describe how disks are subdivided.
9196 <!-- XXX: mention serno stuff -->
9200 A disk can be subdivided in slices.
9202 Slices are named `s0`, `s1` and so on.
9204 For example the disk `ad6` can contain the slice `ad6s3`.
9206 DragonFly support two schemes for slices, MBR and GPT, either of them will manage all slices on a disk:
9208 * 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.
9210 * 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).
9214 Partitions are contained in slices.
9216 Partitions are named `a`, `b` and so on.
9218 DragonFly support 16 partitions per slice, that is `a` through `p`.
9220 For example the partition `ad6s3a` is contained in the slice `ad6s3`.
9222 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):
9224 * [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.
9226 * [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.
9228 ### Local UNIX file systems
9230 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.
9232 DragonFly support two local UNIX file systems, UFS and HAMMER:
9234 * 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.
9236 * [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.
9238 ### Typical disk layout
9240 From the above we see the following typical disk layout scenarios:
9242 * 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.
9244 * 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.
9246 * 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).
9250 [HAMMER(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=HAMMER&section5)
9252 is a rather new file system, under active development.
9254 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 .
9256 All major features except the mirroring are quite well tested as-of the 2.2.1 release.
9258 You should evaluate if HAMMER is suitable for your needs.
9259 <!-- XXX: mention disk and memory requirements for efficient hammer use -->
9261 Examples of ongoing development includes:
9263 * 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).
9265 * Multi master mirroring. For now only one mirror master is supported, but multiple mirror targets, called slaves, are already supported.
9267 * Support for shrinking existing HAMMER file systems. The HAMMER design is prepared for this, utility just have to be written to support it.
9268 <!-- XXX: is this still accurate? Do we really want to mention it here? -->
9272 [HAMMER(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=HAMMER&section5) has several advanced features not found in UFS:
9274 * Large file systems: Up to 1 million TB, also called 1 Exabyte is supported.
9276 * 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.
9278 * 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.
9280 * 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.
9282 * 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).
9284 * 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.
9286 * 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.
9288 More info on HAMMER can be found [here](http://www.dragonflybsd.org/hammer/index.html).
9290 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.
9292 <!-- XXX: mention swapcache, and also how to configure and use it (somewhere else, probably) -->
9296 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.
9298 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
9299 [disklabel64(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel64&section8).
9301 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).
9303 <!-- XXX: mention that disklabel64 is default now -->
9322 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.
9326 # disklabel64 -rw ad6s1 auto
9328 # disklabel64 -e ad6s1 # edit label to add partitions as needed
9331 <!-- XXX: what is all this fuzz about dangerously dedicated? -->
9333 For [disklabel(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel&section8) labels some partitions have certain conventions associated with them.
9336 <tablestyle="width:100%"> Partition | Convention
9337 <tablestyle="width:100%"> `a` | Normally contains the root file system
9338 `b` | Normally contains swap space
9339 `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.
9340 `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`. |
9344 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.
9346 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.
9348 <!-- XXX: gpt allows for way more than 4 partitions... let's remove this stuff above -->
9350 ***Dangerously dedicated*** physical drives are accessed as slice 0.
9352 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.
9354 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).
9356 <!-- XXX: here would probably be the right place to talk about serno -->
9358 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).
9360 <!-- XXX: later talk also about devfs, definitely not here though. also, devfs rules -->
9362 [Example 3-2](disk-organization.html#BASICS-CONCEPT-DISK-MODEL) shows a conceptual model of the disk layout that should help make things clearer.
9364 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.
9366 ***'Table 3-1. Disk Device Codes***'
9369 <tablestyle="width:100%"> Code | Meaning
9370 <tablestyle="width:100%"> `ad` | ATAPI (IDE) disk
9371 `da` | SCSI direct access disk
9372 `acd` | ATAPI (IDE) CDROM
9375 `fd` | Floppy disk |
9379 ***'Example 3-1. Sample Disk, Slice, and Partition Names***'
9382 <tablestyle="width:100%"> Name | Meaning
9383 <tablestyle="width:100%"> `ad0s1a` | The first partition (`a`) on the first slice (`s1`) on the first IDE disk (`ad0`).
9384 `da1s2e` | The fifth partition (`e`) on the second slice (`s2`) on the second SCSI disk (`da1`). |
9388 ***'Example 3-2. Conceptual Model of a Disk***'
9390 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.
9392 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.
9396 ## Mounting and Unmounting File Systems
9398 The file system is best visualized as a tree, rooted at `/`.
9400 The directories, e.g. `/dev` and `/usr`, in the root directory are branches,
9402 which may have their own branches, such as `/usr/local`, and so on.
9404 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.
9406 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.
9410 During the [boot process](boot.html), file systems listed in `/etc/fstab` are automatically mounted (unless they are listed with the `noauto` option).
9412 The `/etc/fstab` file contains a list of lines of the following format:
9415 device mount-point fstype options dumpfreq passno
9417 These parameters have the following meaning:
9419 * `device`: A device name (which should exist), as explained [here](disks-naming.html).
9421 * `mount-point`: A directory (which should exist), on which to mount the file system.
9423 * `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`.
9425 * `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.
9427 * `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.
9429 * `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.
9431 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.
9433 ### The mount Command
9435 The [mount(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=mount§ion8) command is what is ultimately used to mount file systems.
9437 In its most basic form, you use:
9441 # mount device mountpoint
9443 Or, if `mountpoint` is specified in `/etc/fstab`, just:
9449 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:
9453 * `-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.
9455 * `-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.
9457 * `-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.
9459 * `-r`: Mount the file system read-only. This is identical to using the `rdonly` argument to the `-o` option.
9461 * `-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.
9463 * `-u`: Update mount options on the file system.
9467 * `-w`: Mount the file system read-write.
9469 The `-o` option takes a comma-separated list of the options, including the following:
9471 * `nodev:` Do not interpret special devices on the file system. This is a useful security option.
9473 * `noexec`: Do not allow execution of binaries on this file system. This is also a useful security option.
9475 * `nosuid`: Do not interpret setuid or setgid flags on the file system. This is also a useful security option.
9477 ### The umount Command
9479 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.
9481 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.
9483 `-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.
9487 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.
9489 <!-- XXX: talk about LWPs and threads? -->
9491 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.
9493 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.
9495 By default, `ps` only shows you the commands that are running and are owned by you. For example:
9501 PID TT STAT TIME COMMAND
9502 298 p0 Ss 0:01.10 tcsh
9503 7078 p0 S 2:40.88 xemacs mdoc.xsl (xemacs-21.1.14)
9504 37393 p0 I 0:03.11 xemacs freebsd.dsl (xemacs-21.1.14)
9505 48630 p0 S 2:50.89 /usr/local/lib/netscape-linux/navigator-linux-4.77.bi
9506 48730 p0 IW 0:00.00 (dns helper) (navigator-linux-)
9507 72210 p0 R+ 0:00.00 ps
9508 390 p1 Is 0:01.14 tcsh
9509 7059 p2 Is+ 1:36.18 /usr/local/bin/mutt -y
9510 6688 p3 IWs 0:00.00 tcsh
9511 10735 p4 IWs 0:00.00 tcsh
9512 20256 p5 IWs 0:00.00 tcsh
9513 262 v0 IWs 0:00.00 -tcsh (tcsh)
9514 270 v0 IW+ 0:00.00 /bin/sh /usr/X11R6/bin/startx -- -bpp 16
9515 280 v0 IW+ 0:00.00 xinit /home/nik/.xinitrc -- -bpp 16
9516 284 v0 IW 0:00.00 /bin/sh /home/nik/.xinitrc
9517 285 v0 S 0:38.45 /usr/X11R6/bin/sawfish
9519 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.
9521 [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.
9523 The output from [top(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=top§ion1) is similar. A sample session looks like this:
9528 last pid: 72257; load averages: 0.13, 0.09, 0.03 up 0+13:38:33 22:39:10
9529 47 processes: 1 running, 46 sleeping
9530 CPU states: 12.6% user, 0.0% nice, 7.8% system, 0.0% interrupt, 79.7% idle
9531 Mem: 36M Active, 5256K Inact, 13M Wired, 6312K Cache, 15M Buf, 408K Free
9532 Swap: 256M Total, 38M Used, 217M Free, 15% Inuse
9535 PID USERNAME PRI NICE SIZE RES STATE TIME WCPU CPU COMMAND
9536 72257 nik 28 0 1960K 1044K RUN 0:00 14.86% 1.42% top
9537 7078 nik 2 0 15280K 10960K select 2:54 0.88% 0.88% xemacs-21.1.14
9538 281 nik 2 0 18636K 7112K select 5:36 0.73% 0.73% XF86_SVGA
9539 296 nik 2 0 3240K 1644K select 0:12 0.05% 0.05% xterm
9540 48630 nik 2 0 29816K 9148K select 3:18 0.00% 0.00% navigator-linu
9541 175 root 2 0 924K 252K select 1:41 0.00% 0.00% syslogd
9542 7059 nik 2 0 7260K 4644K poll 1:38 0.00% 0.00% mutt
9545 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.
9547 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.
9549 [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.
9551 ## Daemons, Signals, and Killing Processes
9553 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.
9555 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.
9557 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.
9559 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.
9561 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.
9563 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.
9565 `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).
9567 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.
9569 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.
9571 Signals are sent using the [kill(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=kill§ion=1) command, as this example shows.
9573 **Sending a Signal to a Process**
9575 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`.
9577 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).
9581 % ps -ax | grep inetd
9583 198 ?? IWs 0:00.00 inetd -wW
9587 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.
9589 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.
9597 # /bin/kill -s HUP 198
9601 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`.
9603 **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.
9605 Sending other signals is very similar, just substitute `TERM` or `KILL` in the command line as necessary.
9607 **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** .
9616 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`.
9618 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.
9620 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** ]`.
9622 The shell would print out `rm foo[BEEP].bar`.
9624 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.
9626 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:
9629 <tablestyle="width:100%"> Variable | Description
9630 <tablestyle="width:100%"> `USER` | Current logged in user's name.
9631 `PATH` | Colon separated list of directories to search for binaries.
9632 `DISPLAY` | Network name of the X11 display to connect to, if available.
9633 `SHELL` | The current shell.
9634 `TERM` | The name of the user's terminal. Used to determine the capabilities of the terminal.
9635 `TERMCAP` | Database entry of the terminal escape codes to perform various terminal functions.
9636 `OSTYPE` | Type of operating system. e.g., DragonFly.
9637 `MACHTYPE` | The CPU architecture that the system is running on.
9638 `EDITOR` | The user's preferred text editor.
9639 `PAGER` | The user's preferred text pager.
9640 `MANPATH` | Colon separated list of directories to search for manual pages. |
9644 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`:
9647 % setenv EDITOR /usr/pkg/bin/emacs
9649 Under Bourne shells:
9652 % export EDITOR="/usr/pkg/bin/emacs"
9654 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`.
9656 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.
9658 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.
9660 ### Changing Your Shell
9662 <!-- XXX: does chsh still exist? chpass will do, too -->
9664 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.
9666 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:
9670 % chsh -s /usr/pkg/bin/bash
9672 **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.
9674 For example, if you installed `bash` by hand and placed it into `/usr/local/bin`, you would want to:
9678 # echo "/usr/local/bin/bash" >> /etc/shells
9684 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.
9686 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.
9688 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.
9690 ## Devices and Device Nodes
9692 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`.
9694 For example, `acd0` is the first IDE CDROM drive, while `kbd0` represents the keyboard.
9696 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.
9698 The device nodes in the `/dev` directory are created and destroyed automatically on DragonFly >= 2.4, by means of the device file system (devfs).
9702 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®:
9704 * [a.out(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=a.out&section=5)
9706 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.
9710 The SVR3 object format. The header now comprises a section table, so you can have more than just .text, .data, and .bss sections.
9712 * [elf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=elf&section=5)
9714 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.
9716 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.
9718 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.
9720 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.
9722 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.
9724 <!-- XXX: do we really need all this bullshit about file formats? -->
9726 ## For More Information
9730 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:
9734 `command` is the name of the command you wish to learn about. For example, to learn more about `ls` command type:
9738 The online manual is divided up into numbered sections:
9741 1. System calls and error numbers.
9742 1. Functions in the C libraries.
9745 1. Games and other diversions.
9746 1. Miscellaneous information.
9747 1. System maintenance and operation commands.
9748 1. Kernel internals.
9750 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:
9755 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.
9757 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:
9763 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.
9765 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:
9776 which does the same thing.
9780 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:
9784 For a brief introduction, type `h`. For a quick command reference, type `?`.
9788 Dports is DragonFly's own third-party software build system. It is based on FreeBSD's Ports Collection. Differences between ports and DPorts are intentionally kept to a minimum, both to maintain familiarity for mutual users of both operating systems and also to leverage the tremendous amount of work the FreeBSD contributors put into ports. DPorts can and does feature ports unique to DragonFly, so it's truly a native system.
9790 The __pkgng__ tool called "pkg" is a modern and fast binary package manager. It was developed for FreeBSD, but PC-BSD used it in production first, followed soon after by DragonFly. In the future, it will be the only binary package manager on FreeBSD just as it is for DPorts.
9792 __pkgng__ is not a replacement for port management tools like `ports-mgmt/portmaster` or `ports-mgmt/portupgrade`. While `ports-mgmt/portmaster` and `ports-mgmt/portupgrade` can install third-party software from both binary packages and DPorts, __pkgng__ installs only binary packages.
9794 ## Getting started with pkgng
9796 DragonFly daily snapshots and Releases (starting with 3.4) come with __pkgng__ already installed. However upgrades from earlier releases won't have it. If the "pkg" program is missing on the system for any reason, it can be quickly bootstrapped without having to build it from source.
9798 To ensure __pkgng__ on a DragonFly BSD 3.4 or higher system is ready for use, run the following BEFORE you try to use `pkg` the first time:
9801 # make dports-create
9806 Since you may need to manually edit the configuration file `/usr/local/etc/pkg.conf` here is the
9807 usual command to edit it using the vi editor:
9809 # vi /usr/local/etc/pkg.conf
9811 Before using consult the man page (`man pkg`) and then try things like these examples:
9813 # pkg search editors
9816 To bootstrap __pkgng__ with a download on a very old version of DragonFly that is still using `pkgsrc` run:
9818 # make pkg-bootstrap
9820 # pkg-static install -y pkg
9823 Note that this step is unnecessary for any newly installed release from DragonFly 3.4 onwards.
9825 ## Configuring pkgng
9827 Information previously contained in here worked for older versions of pkg, but as pkgng has undergone some changes, so too do the configurations.
9829 Previously /usr/local/etc/pkg.conf was used and reference to a PACKAGESITE was made. This might still work but it'll complain.
9832 pkg: PACKAGESITE in pkg.conf is deprecated. Please create a repository configuration file
9833 Updating repository catalogue
9834 pkg: Warning: use of http:// URL scheme with SRV records is deprecated: switch to pkg+http://
9836 Insead, listen to the errors. Throw an octothorpe in front of that packagesite line, save it, and move on.
9838 Go to /usr/local/etc/pkg/repos/
9840 You should see something like this with an ls
9842 df-latest.conf.sample df-releases.conf.sample
9844 cp or mv one of them to be .conf
9846 edit the one you choose and make the following changes. (I edited the latest version)
9849 url : pkg+http://mirror-master.dragonflybsd.org/dports/${ABI}/L\
9852 signature_type : NONE,
9854 fingerprints : /usr/share/fingerprints,
9858 Depending on when and how you installed and/or upgraded, you may have to chmod 644 the file first to be able to edit it.
9860 ## Basic pkgng Operations
9862 Usage information for __pkgng__ is available in the pkg(8) manual page, or by running `pkg` without additional arguments.
9864 Each __pkgng__ command argument is documented in a command-specific manual page. To read the manual page for `pkg install`, for example, run either:
9869 ## Obtaining Information About Installed Packages with pkgng
9871 Information about the packages installed on a system can be viewed by running `pkg info`. Similar to pkg_info(1), the package version and description for all packages will be listed. Information about a specific package is available by running:
9873 # pkg info packagename
9875 For example, to see which version of __pkgng__ is installed on the system, run:
9878 pkg-1.0.12 New generation package manager
9880 ## Installing and Removing Packages with pkgng
9882 In general, most DragonFly users will install binary packages by typing:
9884 # pkg install <packagename>
9886 For example, to install curl:
9890 Updating repository catalogue
9891 Repository catalogue is up-to-date, no need to fetch fresh copy
9892 The following packages will be installed:
9894 Installing ca_root_nss: 3.13.5
9895 Installing curl: 7.24.0
9897 The installation will require 4 MB more space
9899 1 MB to be downloaded
9901 Proceed with installing packages [y/N]: y
9902 ca_root_nss-3.13.5.txz 100% 255KB 255.1KB/s 255.1KB/s 00:00
9903 curl-7.24.0.txz 100% 1108KB 1.1MB/s 1.1MB/s 00:00
9904 Checking integrity... done
9905 Installing ca_root_nss-3.13.5... done
9906 Installing curl-7.24.0... done
9908 The new package and any additional packages that were installed as dependencies can be seen in the installed packages list:
9911 ca_root_nss-3.13.5 The root certificate bundle from the Mozilla Project
9912 curl-7.24.0 Non-interactive tool to get files from FTP, GOPHER, HTTP(S) servers
9913 pkg-1.0.12 New generation package manager
9915 Packages that are no longer needed can be removed with `pkg delete`. For example, if it turns out that curl is not needed after all:
9918 The following packages will be deleted:
9922 The deletion will free 3 MB
9924 Proceed with deleting packages [y/N]: y
9925 Deleting curl-7.24.0_1... done
9927 ## Upgrading Installed Packages with pkgng
9929 Packages that are outdated can be found with `pkg version`. If a local ports tree does not exist, pkg-version(8) will use the remote repository catalogue, otherwise the local ports tree will be used to identify package versions.
9931 Packages can be upgraded to newer versions with __pkgng__. Suppose a new version of curl has been released. The local package can be upgraded to the new version:
9934 Updating repository catalogue
9935 repo.txz 100% 297KB 296.5KB/s 296.5KB/s 00:00
9936 The following packages will be upgraded:
9938 Upgrading curl: 7.24.0 -> 7.24.0_1
9940 1 MB to be downloaded
9942 Proceed with upgrading packages [y/N]: y
9943 curl-7.24.0_1.txz 100% 1108KB 1.1MB/s 1.1MB/s 00:00
9944 Checking integrity... done
9945 Upgrading curl from 7.24.0 to 7.24.0_1... done
9947 ## Auditing Installed Packages with pkgng
9949 Occasionally, software vulnerabilities may be discovered in software within DPorts. __pkgng__ includes built-in auditing. To audit the software installed on the system, type:
9953 # Advanced pkgng Operations
9955 ## Automatically Removing Leaf Dependencies with pkgng
9957 Removing a package may leave behind unnecessary dependencies, like `security/ca_root_nss` in the example above. Such packages are still installed, but nothing depends on them any more. Unneeded packages that were installed as dependencies can be automatically detected and removed:
9960 Packages to be autoremoved:
9963 The autoremoval will free 723 kB
9965 Proceed with autoremoval of packages [y/N]: y
9966 Deinstalling ca_root_nss-3.13.5... done
9968 ## Backing Up the pkgng Package Database
9970 __pkgng__ includes its own package database backup mechanism. To manually back up the package database contents, type:
9972 # pkg backup -d <pkgng.db>
9974 Additionally, __pkgng__ includes a periodic(8) script to automatically back up the package database daily if `daily_backup_pkgng_enable` is set to `YES` in periodic.conf(5). To prevent the `pkg_install` periodic script from also backing up the package database, set `daily_backup_pkgdb_enable` to `NO` in periodic.conf(5).
9976 To restore the contents of a previous package database backup, run:
9978 # pkg backup -r </path/to/pkgng.db>
9980 ## Removing Stale pkgng Packages
9982 By default, __pkgng__ stores binary packages in a cache directory as defined by `PKG_CACHEDIR` in pkg.conf(5). When upgrading packages with pkg upgrade, old versions of the upgraded packages are not automatically removed.
9984 To remove the outdated binary packages, type:
9988 ##Modifying pkgng Package Metadata
9990 __pkgng__ has a built-in command to update package origins. For example, if `lang/php5` was originally at version 5.3, but has been renamed to lang/php53 for the inclusion of version 5.4, the package database can be updated to deal with this. For __pkgng__, the syntax is:
9992 # pkg set -o <category/oldport>:<category/newport>
9994 For example, to change the package origin for the above example, type:
9996 # pkg set -o lang/php5:lang/php53
9998 As another example, to update lang/ruby18 to lang/ruby19, type:
10000 # pkg set -o lang/ruby18:lang/ruby19
10002 As a final example, to change the origin of the libglut shared libraries from graphics/libglut to graphics/freeglut, type:
10004 # pkg set -o graphics/libglut:graphics/freeglut
10006 _Note_: When changing package origins, in most cases it is important to reinstall packages that are dependent on the package that has had the origin changed. To force a reinstallation of dependent packages, type:
10008 # pkg install -Rf graphics/freeglut
10010 # Building DPorts from source
10012 The average user will probably not build packages from source. However, it's easy to do and it can be done even when packages have already been pre-installed on the system. Common reasons to build from source are:
10014 * The port is new and there's no pre-binary available yet
10015 * The pre-built binaries use the default options and the user needs a package built with a different set of options
10016 * Testing FreeBSD port in order to patch them and submit to DPorts
10017 * The user just prefers building from source
10019 ## Installing DPorts tree
10021 DragonFly 3.4 or later is the minimum version that can build DPorts from source.
10023 It's probably that pkgsrc binaries are already installed because it comes bootstrapped with new systems. It is necessary to rename `/usr/pkg` directory so that the existing pkgsrc binary tools and libraries don’t get accidentally used while building DPorts, causing breakage. For the installation of the DPorts tree, type:
10026 # make dports-create-shallow
10028 If the `/usr/pkg directory` has already been renamed, `git` won’t be in the search path any more. One option is to download a tarball of DPorts and unpack it. To do this, type:
10031 # make dports-download
10033 For future updates, pull delta changes via `git` is fastest, so it is suggested to convert the static tree to a git repository by typing:
10035 # cd /usr/dports/devel/git
10038 # rm -rf /usr/dports
10039 # make dports-create-shallow
10041 The git repository is hosted on the [github account of John Marino](https://github.com/jrmarino/DPorts/#readme).
10045 Building from source works similar to ports and pkgsrc: cd into the appropriate program's directory, and type 'make'. 'make install' to install the software, 'make clean' to clean up work files, and so on. Use 'make config-recursive' if you want to set all the port's options, and the options of its dependencies, immediately instead of during the build.
10047 To take all the default build options and avoid getting the pop-up dialog box, set `NO_DIALOG=yes` on either the command line or the make.conf file.
10049 If you just want to set the options for one package, and accept the default for all of its dependencies, do 'make config' in the package in you want non-default options, and then 'make NO_DIALOG=yes'. Note that this is only necessary if you want to build from source with a non-default set of options, or if no pre-built binary package is available yet.
10052 * How fix/add broken ports: [[docs/howtos/fixdports]]
10053 * [Trick: How to get i386-only software via dports](http://leaf.dragonflybsd.org/mailarchive/users/2013-06/msg00023.html)
10057 DragonFly, up to and including version 3.4, used pkgsrc to manage third party software packages. DragonFly switched to dports at the 3.6 release.
10059 This page is still useful for anyone wanting to use pkgsrc, but the recommended packaging method is dports, which is covered in a similar document here:
10061 [http://www.dragonflybsd.org/docs/howtos/HowToDPorts/](http://www.dragonflybsd.org/docs/howtos/HowToDPorts/)
10065 # pkgsrc on DragonFly
10067 DragonFly uses a specially crafted Makefile in /usr and a git mirror
10068 of the official pkgsrc repository to make pkgsrc distribution more user-friendly.
10070 The basics of the pkgsrc system can be found in NetBSD's [Pkgsrc Guide](http://www.netbsd.org/docs/pkgsrc/), and can be considered the canonical resource.
10077 [Pkgsrc](http://www.pkgsrc.org) is a packaging system that was originally created for NetBSD. It has been ported to DragonFly, along with other operating systems. Pkgsrc is very similar to FreeBSD's ports mechanism.
10081 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.
10083 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.
10085 **Binary Package Benefits**
10087 * A compressed package tarball is typically smaller than the compressed tarball containing the source code for the application.
10089 * 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.
10091 * Packages do not require any understanding of the process involved in compiling software on DragonFly.
10093 **Pkgsrc source Benefits**
10095 * 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.
10097 * 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.
10099 * The licensing conditions of some software distributions forbid binary distribution. They must be distributed as source code.
10101 * 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.
10103 * If you have local patches, you will need the source in order to apply them.
10105 * Some people like having code around, so they can read it if they get bored, hack it, debug crashes, borrow from it (license permitting, of course), and so on.
10107 To keep track of pkgsrc releases subscribe to the [NetBSD pkgsrc users mailing list](http://www.netbsd.org/MailingLists/pkgsrc-users) and the [NetBSD pkgsrc users mailing list](http://www.netbsd.org/MailingLists/tech-pkgsrc). It's also useful to watch the [DragonFly User related mailing list](http://leaf.dragonflybsd.org/mailarchive/) as errors with pkgsrc on DragonFly should be reported there.
10109 **Warning:** Before installing any application, you should check http://www.pkgsrc.org/ for security issues related to your application.
10111 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.
10113 **Note:** Binary packages and source packages are effectively the same software and can be manipulated with the same pkg_* tools.
10115 ## Installing pkgsrc
10117 The basic pkgsrc tools are provided with every DragonFly system as part of installation. However, you still need to download the pkgsrc tree for building applications with these tools.
10119 Set GITHOST in /etc/make.conf or set it as an environment variable to select a different download location, if desired. See mirrors page for available mirrors.
10121 This downloads the stable version of the pkgsrc tree from the default mirror, if you didn't set GITHOST. As root:
10124 # make pkgsrc-create
10126 to fetch the intial pkgsrc repository from the net, or
10129 # make pkgsrc-update
10133 **Note**: If your DragonFly install is not up to date, you might have ended up with an old release of the pkgsrc tree.
10138 will show what release you are on. See Tracking the stable branch for more information.
10140 ### Tracking the stable branch
10142 There are quarterly releases of pkgsrc that are specifically designed for stability. You should in general follow these, rather than the bleeding edge pkgsrc. When a new branch is out you need to set up a local branch tracking that one. 'make pkgsrc-update' will not do this for you.
10144 To see the available remote branches:
10150 To create a local branch, tracking the remote quarterly release:
10153 # git branch pkgsrc-2010Q4 origin/pkgsrc-2010Q4
10155 Branch naming format is 'pkgsrc-YYYYQX', where YYYY is the year and QX is quarters 1-4 of the year. Check [pkgsrc.org](http://www.pkgsrc.org/) to see the name of the latest stable branch.
10157 After adding a new branch, it can be downloaded with:
10160 # git checkout pkgsrc-2010Q4
10163 ## Dealing with pkgsrc packages
10165 The following section explains how to find, install and remove pkgsrc packages.
10167 ### Finding Your Application
10169 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:
10171 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.
10174 fvwm-2.4.20nb1 Newer version of X11 Virtual window manager
10175 fvwm-2.5.24 Development version of X11 Virtual window manager
10176 fvwm-themes-0.6.2nb8 Configuration framework for fvwm2 with samples
10177 fvwm-wharf-1.0nb1 Copy of AfterStep's Wharf compatible with fvwm2
10178 fvwm1-1.24rnb1 Virtual window manager for X
10180 # pkg_search -v fvwm-2.5
10181 Name : fvwm-2.5.24-50
10182 Dir : wm/fvwm-devel
10183 Desc : Development version of X11 Virtual window manager
10185 Deps : perl>#5.0 gettext-lib>0.14.5 [...]
10187 Its also possible to issue the command
10190 # bmake search key='package you are looking for'
10192 from the `/usr/pkgsrc` directory.
10194 It's also possible to browse website that show all the available pkgsrc packages, such as [http://pkgsrc.se/](http://pkgsrc.se) .
10196 ### Installing applications
10198 Downloading a binary package is almost always faster than building from source, but not all programs in pkgsrc can be redistributed as a binary. In most cases, you will want to download a binary package if possible, and otherwise build from source if it's not available.
10200 The `bin-install` target on DragonFly (with pkgsrc from 2011/02/07 and later) will do just that:
10202 # cd /usr/pkgsrc/misc/screen
10203 # bmake bin-install clean
10205 This will download and install the appropriate `screen` binary package if it exists, and try building from source if it can't complete the download.
10207 ### Installing applications, source only
10209 Packages are built by going into the appropriate directory and issuing `bmake install clean`. For example, to build the *screen* package you need to issue the following commands.
10211 # cd /usr/pkgsrc/misc/screen
10212 # bmake install clean
10214 To find out the options that can affect how a program is built:
10216 # bmake show-options
10220 # bmake PKG_OPTIONS.<package_name>="-option1 option2" install clean
10222 Listing an option enables it. Listing an option with a "-" before it disables the option.
10224 To make these option changes permanent for every future build or upgrade of this package, put a similar line in `/usr/pkg/etc/mk.conf`:
10226 . PKG_OPTIONS.<package_name>=-option1 option2
10228 ### Installing applications, binary only
10230 Binary packages can be installed using *pkg_radd*:
10234 This program works by setting the `PKG_PATH` environment variable to the appropriate path for the operating system and architecture to a remote repository of binary packages, and then using *pkg_add* to get packages. This will install most packages, but will not upgrade packages that are already installed.
10236 You can manually set `BINPKG_BASE` and use *pkg_add* to get the same effect, using a different server.
10238 # setenv BINPKG_BASE http://mirror-master.dragonflybsd.org/packages
10241 #### Issues with pre-built packages
10243 * The default remote repository for binary packages tracks quarterly pkgsrc releases, so your local install of pkgsrc should be the same quarterly release.
10244 * Some packages are not licensed for distribution in binary form, so they may be able to build on DragonFly but won't be available with *pkg_radd*. If it fails, try going to that package's directory and install the package manually as described above.
10245 * If you upgrade to an new DEVELOPMENT version of DragonFly very early (i.e. shortly after the branch), it might be possible that *pkg_radd* fails to install packages. This is due the fact, that it takes some time to built binary packages and thus, there are no binary packages available on the mirrors yet. Usually you'll see an announcement on the lists once the first packages for DEVELOPMENT are ready.
10247 ### List all installed applications
10249 To obtain a list of all the packages that are installed on your system:
10253 To see if certain packages have been installed, filter for the name of the package. This example will show all *xorg*-related packages currently installed on the system:
10255 # pkg_info | grep xorg
10257 ### Removing packages
10259 If a program was installed as a package:
10261 # pkg_delete packagename
10263 If a package was installed from the source files, you can also change to the directory they were installed from and issue the command:
10267 Note that these methods are effectively interchangeable. Either will work whether the package was originally installed from source or binary.
10269 #### Remove associated files needed for building a package
10271 To remove the work file from building a package, and the package's dependencies:
10273 # bmake clean clean-depends
10275 This can be combined with other steps:
10277 # bmake install clean clean-depends
10279 ## Upgrading packages
10281 There's a number of ways to upgrade pkgsrc; some of these are built in and some are packages installable with pkgsrc. This list is not necessarily comprehensive.
10283 ### Update pkgsrc system packages
10285 **Note**: Sometimes basic pkgsrc tools; *bmake*, *pkg_install* and *bootstrap-mk-files* need to be upgraded. However, they can't be deleted and replaced since you need that tool to accomplish replacement. The solution is to build a separate package before deletion, and install that package.
10287 # cd /usr/pkgsrc/devel/bmake
10289 # cd /usr/pkgsrc/pkgtools/pkg_install
10291 # cd /usr/pkgsrc/pkgtools/bootstrap-mk-files
10293 # env USE_DESTDIR=yes bmake package
10294 # bmake clean-depends clean
10296 And go to the packages directory and install the binary package with
10298 # cd /usr/pkgsrc/packages/All
10299 # pkg_add -u <pkg_name> (i.e. the name of the .tgz file).
10302 Performed in the `/usr/pkgsrc` directory that correlates with the installed package, the software is first built and then replaced.
10304 # cd /usr/pkgsrc/chat/ircII
10307 ### pkg_rolling-replace
10309 *pkg_rolling-replace* replaces packages one by one and you can use it for a better way of package management. Actually it does `bmake replace` on one package at a time, sorting the packages being replaced according to their interdependencies, which avoids most duplicate rebuilds. Once *pkg_rolling-replace* is installed you can update the packages through the following steps.
10311 # cd /usr && make pkgsrc-update
10312 # pkg_rolling-replace -u
10316 Downloads and installs binary packages. Check the [[mirrors]] page for sites carrying binary packages to use with pkgin. You can run the following commands to get the packages updated. This assumes that *pkgin* is already configured. Please consult the documentation and the man page on how to do so.
10319 # pkgin full-upgrade
10323 It updates packages by removing them and rebuilding them. Warning: programs are unavailable until a rebuild finishes. If they don't rebuild, it won't work. *pkg_chk* requires a few steps in order to work correctly. They are listed here.
10325 # pkg_chk -g # make initial list of installed packages
10326 # pkg_chk -r # remove all packages that are not up to date and packages that depend on them
10327 # pkg_chk -a # install all missing packages (use binary packages, this is the default)
10328 # pkg_chk -as # install all missing packages (build from source)
10330 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.
10334 Point at a local or online binary archive location to download and update packages.
10338 This requires that you've set up rpkgmanager first. Read more about rpkgmanager [[here|docs/howtos/rpkgmanager/]].
10340 # yes | rpkgmanager.rb
10342 ## Start pkgsrc applications on system startup
10344 Packages often install rc.d scripts to control software running on startup. To specify where the rc.d scripts from the installed packages should go, add the following lines to your `/usr/pkg/etc/mk.conf` file:
10346 RCD_SCRIPTS_DIR=/etc/rc.d
10347 PKG_RCD_SCRIPTS=YES
10349 This option can be set in the environment to activate it for binary packages. These packages will still have to be enabled in `/etc/rc.conf/` to run at boot. If these options aren't set, the rc file will be placed in `/usr/pkg/share/examples/rc.d/` and will need to be manually copied over to `/etc/rc.d`.
10351 Many other options can be set in this file; see `/usr/pkgsrc/mk/defaults/mk.conf` for examples.
10353 ## Miscellaneous topics
10355 ### Post-installation Activities
10357 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.
10358 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:
10360 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
10362 # pkg_info -L foopackage-1.0.0 | less
10364 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
10366 # pkg_info | grep -i foopackage
10368 will find all the installed packages that have *foopackage* in the package name. Replace *foopackage* in your command line as necessary.
10370 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. 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
10372 # pkg_info foopackage-1.0.0
10374 A `WWW:` line, if present, should provide a URL for the application's web site.
10376 ### Dealing with Broken Packages
10378 If you come across a package that does not work for you, there are a few things you can do, including:
10380 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!
10382 1. Send email to the maintainer of the package first. Type `bmake maintainer` or read the `Makefile` to find the maintainer's email address. Remember to include the name and version of the port (send the `$NetBSD:` line from the `Makefile`) and the output leading up to the error when you email the maintainer. If you do not get a response from the maintainer, you can try [users](http://leaf.dragonflybsd.org/mailarchive/) .
10384 1. Grab a pre-built package from an [[mirror|mirrors]] site near you.
10388 Packages that can be built within the pkgsrc framework but are not yet necessarily ready for production use can be found in [http://pkgsrc-wip.sourceforge.net](http://pkgsrc-wip.sourceforge.net). These packages need to be downloaded separately; check the website for details. Packages in this collection are in development and may not build successfully.
10392 * More information: The pkgsrc guide [http://www.netbsd.org/Documentation/pkgsrc/](http://www.netbsd.org/Documentation/pkgsrc/)
10394 * Web interface for searching packages: [http://www.pkgsrc.se](http://www.pkgsrc.se)
10396 * Ways to upgrade packages [http://wiki-static.aydogan.net/How_to_upgrade_packages](http://wiki-static.aydogan.net/How_to_upgrade_packages)
10398 * To search and/or report bugs against packages in pkgsrc, look at [http://www.netbsd.org/support/send-pr.html](http://www.netbsd.org/support/send-pr.html) - use category 'pkg'.
10400 * The #pkgsrc IRC channel on Freenode
10402 * The #dragonflybsd IRC channel on EFnet
10404 # The X Window System
10405 ***Updated for X.Org's X11 server by Ken Tom and Marc Fonvieille. Updated for DragonFly by Victor Balada Diaz. Updated for 2014 pkgng by Warren Postma***
10411 This chapter will cover the installation and some configuration of the usual way of giving your Dragonfly BSD system an X-Windows style Graphical User Interface (GUI) and a modern Desktop Environment. In Unix systems, the graphical drawing system is provided by the combination of an X11R6 compliant X-Windows Server, such as the X.org server, and other software such as Window Managers and Desktop Environments. This multi-layered approach may be surprising to people coming from systems like the Mac or like Windows where these components are not so flexible, or provided by so many separately installed and configured pieces.
10413 For more information on the video hardware support in X.org, check the [X.org](http://www.x.org/) web site. If you have problems configuring your X server, just search the web. There are lots of tutorials and guides on how to set up your X properly, if the information in this page is not enough for your situation.
10415 Before reading this chapter, you should know how to install additional third-party software. Read the `dports` section of the documentation, for DragonFly 3.4 and later.
10417 You may find the FreeBSD X Configuration instructions apply exactly and unchanged in DragonFly BSD.
10418 They are found [[here|http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/x-config.html]]
10424 X.Org is the most popular free implementation of the X11 specification. The X11 specification is an open standard, and there are other implementations, some commercial, and some free.
10426 ### The Window Manager and the Desktop Environment
10428 An X Server is a very low level piece of software. It does not provide any way to move windows around or resize them. It does not provide a title bar on the top of your windows, or a dock, or any menus.
10430 These things are the job, in the oldest style of X environment, of your window manager, or in more recent times, of a Desktop Environment.
10432 Installing X.org by itself does not give you any window manager or any desktop environment. You will have to choose one and install it yourself. Until you select one, your system will not be usable.
10434 There are dozens of window managers and desktop environments available for X. The most retro ones you might chose include `fvwm` and `twm` which have that retro 1980s workstation look and feel. There are also window managers included inside modern desktop environments like XFCE, KDE and Gnome.
10436 If you are brand new and don't know what to do, select the XFCE4 desktop and follow those instructions.
10437 Every desktop environment and window manager also has a different configuration mechanism. Read your chosen environment's documentation to learn more. Some are configured by text files alone, and some (like KDE and Gnome) have sophisticated graphical configuration utilities and "control panels".
10439 Note that XFCE4 and Gnome and KDE do not require you to install any window manager as they include one automatically.
10443 **X.org** is currently available in the DragonFly dports collection.
10447 pkg install xorg-7.7
10449 By the time you read this, it might be a newer version of xorg than 7.7, you can also try this general command:
10455 You may need to add the following lines to `/etc/rc.conf` for regular PCs but you might not want to set these two lines to NO instead on a Virtual Machine as they cause problems in Dragonfly BSD 3.4 through 3.6:
10460 Also see below about enabling `moused` in rc.conf, which may be required for you to see your mouse pointer in X.
10462 As of version 7.3, Xorg can often work without any configuration file by simply typing at prompt:
10468 If this does not work, or if the default configuration is not acceptable, then X11 must be configured manually. For example, if X11 does not detect your mouse then you will not get a mouse pointer, you will get a desktop (either a color or a dotted-pattern) but moving your mouse will not result in you seeing a mouse pointer move around. Also, you might get a garbled display, or no display at all. If any of these happen to you, you need to do some manual configuration of X.org, which means a configuration text file.
10470 Configuration of X11 is a multi-step process. The first step is to build an initial configuration file. As the super user, simply run:
10475 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.
10477 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:
10481 # Xorg -config xorg.conf.new -retro
10483 The -retro option is now required or you will only get a black desktop when testing. This retro mode is an empty X desktop with a dot pattern on the background and an X cursor in the center. If the mouse is working, you should be able to move it.
10485 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.
10487 **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`:
10491 Tune the `xorg.conf.new` configuration file to taste and move it to where [Xorg(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=xorg§ion=1) can find it. This is typically `/etc/X11/xorg.conf` or `/usr/pkg/xorg/lib/X11/xorg.conf`.
10495 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).
10497 ## The X Display Manager
10499 ***Contributed by Seth Kingsley.***
10503 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.
10505 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.
10509 The **XDM** daemon program is located in `/usr/pkg/bin/xdm`. This program can be run at any time as `root` and it will start managing the X display on the local machine. If **XDM** is to be run every time the machine boots up, a convenient way to do this is by adding an entry to `/etc/ttys`. For more information about the format and usage of this file, see [ Section 17.3.2.1](term.html#TERM-ETCTTYS). There is a line in the default `/etc/ttys` file for running the **XDM** daemon on a virtual terminal:
10513 ttyv8 "/usr/pkg/bin/xdm -nodaemon" xterm off secure
10515 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.
10517 ### Configuring XDM
10519 The **XDM** configuration directory is located in `/var/lib/xdm`. The sample configuration files are in `/usr/pkg/share/examples/xdm/`, in this directory there are several files used to change the behavior and appearance of **XDM** . Typically these files will be found:
10522 <tablestyle="width:100%"> **File** | **Description**
10523 <tablestyle="width:100%"> `Xaccess` | Client authorization ruleset.
10524 `Xresources` | Default X resource values.
10525 `Xservers` | List of remote and local displays to manage.
10526 `Xsession` | Default session script for logins.
10527 `Xsetup_`* | Script to launch applications before the login interface.
10528 `xdm-config` | Global configuration for all displays running on this machine.
10529 `xdm-errors` | Errors generated by the server program.
10530 `xdm-pid` | The process ID of the currently running XDM. |
10534 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).
10536 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.
10540 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.
10544 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.
10548 This is a list of the remote displays the chooser should provide as choices.
10552 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.
10556 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`.
10560 This contains settings in the form of app-defaults that are applicable to every display that this installation manages.
10564 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.
10566 ### Running a Network Display Server
10568 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:
10572 ! SECURITY: do not listen for XDMCP or Chooser requests
10574 ! Comment out this line if you want to manage X terminals with xdm
10576 DisplayManager.requestPort: 0
10578 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.
10580 ### Replacements for XDM
10582 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.
10586 ## Desktop Environments
10588 ***Contributed by Valentino Vaschetto. ***
10590 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** .
10596 **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.
10598 #### Installing GNOME
10600 **GNOME** can be easily installed from a package or from the pkgsrc framework:
10602 To install the **GNOME** package from the network, simply type:
10604 # pkg install gnome-desktop
10606 To build **GNOME** from source, if you have the pkgsrc tree on your system:
10608 # cd /usr/pkgsrc/meta-pkgs/gnome
10610 # bmake install clean
10612 Once **GNOME** is installed, the X server must be told to start **GNOME** instead of a default window manager.
10614 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.
10616 **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:
10620 % echo "/usr/pkg/bin/gnome-session" > ~/.xinitrc
10622 Next, type `startx`, and the **GNOME** desktop environment will be started.
10624 **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** :
10628 % echo "#!/bin/sh" > ~/.xsession
10630 % echo "/usr/pkg/bin/gnome-session" >> ~/.xsession
10632 % chmod +x ~/.xsession
10634 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** .
10636 #### Anti-aliased Fonts with GNOME
10638 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).
10640 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.
10646 **KDE** is an easy to use contemporary desktop environment. Some of the things that **KDE** brings to the user are:
10648 * A beautiful contemporary desktop
10650 * A desktop exhibiting complete network transparency
10652 * An integrated help system allowing for convenient, consistent access to help on the use of the **KDE** desktop and its applications
10654 * Consistent look and feel of all **KDE** applications
10656 * Standardized menu and toolbars, keybindings, color-schemes, etc.
10658 * Internationalization: **KDE** is available in more than 40 languages
10660 * Centralized consisted dialog driven desktop configuration
10662 * A great number of useful **KDE** applications
10664 **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/).
10666 #### Installing KDE
10668 Just as with **GNOME** or any other desktop environment, the easiest way to install **KDE** is through the pkgsrc framework or from a package:
10670 To install the **KDE** 4.10 package from the network, simply type:
10672 # pkg install kde-4.10
10674 To build **KDE** from source, using the pkgsrc framework:
10676 # cd /usr/pkgsrc/meta-pkgs/kde3
10678 # bmake install clean
10680 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:
10682 % echo "exec startkde" > ~/.xinitrc
10684 Now, whenever the X Window System is invoked with `startx`, **KDE** will be the desktop.
10686 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.
10688 #### More Details on KDE
10690 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.
10692 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.
10694 #### The KDE Display Manager
10696 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.
10698 To enable **kdm** , the `ttyv8` entry in `/etc/ttys` has to be adapted. The line should look as follows:
10701 ttyv8 "/usr/pkg/bin/kdm -nodaemon" xterm on secure
10708 **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:
10710 * A simple, easy-to-handle desktop
10712 * Fully configurable via mouse, with drag and drop, etc
10714 * Main panel similar to **CDE** , with menus, applets and applications launchers
10716 * Integrated window manager, file manager, sound manager, **GNOME** compliance module, and other things
10718 * Themeable (since it uses GTK+)
10720 * Fast, light and efficient: ideal for older/slower machines or machines with memory limitations
10722 More information on **XFce** can be found on the [XFce website](http://www.xfce.org/).
10724 #### Installing XFce
10726 A binary package for **XFce** exists. To install, simply type:
10730 This should install the main xfce4 desktop package, and most of the required components.
10732 Alternatively, to build from source, use the pkgsrc framework:
10736 # cd /usr/pkgsrc/meta-pkgs/xfce4
10738 # bmake install clean
10740 Now, tell the X server to launch **XFce** the next time X is started. Simply type this:
10742 % echo "/usr/pkg/bin/startxfce4" > ~/.xinitrc
10744 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).
10746 <!-- XXX: FreeBSD's handbook has a nice user-oriented section about X applications here. maybe we should have one, too -->
10750 # Configuration and Tuning
10752 ***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.***
10758 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.
10760 After reading this chapter, you will know:
10762 * How to efficiently work with file systems and swap partitions.
10764 * The basics of `rc.conf` configuration and `rc.d` startup systems.
10766 * How to configure and test a network card.
10768 * How to configure virtual hosts on your network devices.
10770 * How to use the various configuration files in `/etc`.
10772 * How to tune DragonFly using `sysctl` variables.
10774 * How to tune disk performance and modify kernel limitations.
10776 Before reading this chapter, you should:
10778 * Understand UNIX® and DragonFly basics ([Chapter 3](basics.html)).
10780 * Be familiar with the basics of kernel configuration/compilation ([Chapter 9](kernelconfig.html)).
10782 ## Initial Configuration
10784 ### Partition Layout
10786 #### Base Partitions
10788 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`.
10789 <!-- 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? -->
10791 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.
10793 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.
10795 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.
10797 #### Swap Partition
10799 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.
10800 <!-- XXX: do we really recommend double the RAM for swap? IMHO the amount of RAM should be more than enough -->
10802 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.
10804 #### Why Partition?
10806 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`.
10808 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.
10809 <!-- XXX: again, same story about the edges of disks... -->
10813 CategoryHandbook-configuration
10815 ## Core Configuration
10817 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.
10819 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.
10821 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.
10823 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:
10827 hostname="node15.example.com"
10829 network_interfaces="fxp0 lo0"
10831 ifconfig_fxp0="inet 10.1.1.1"
10837 defaultrouter="10.1.1.254"
10845 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.
10847 Upgrading the system using `make world` will not overwrite the `rc.conf` file, so system configuration information will not be lost.
10851 CategoryHandbook-configuration
10853 ## Application Configuration
10855 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.
10857 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.
10859 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.
10861 For example, consider the contents of the directory `/usr/pkg/etc/httpd`:
10867 -rw-r--r-- 1 root wheel - 34K Jan 11 12:04 httpd.conf
10869 -rw-r--r-- 1 root wheel - 13K Jan 11 12:02 magic
10871 -rw-r--r-- 1 root wheel - 28K Jan 11 12:02 mime.types
10873 -rw-r--r-- 1 root wheel - 11K Jan 11 12:02 ssl.conf
10881 ## Starting Services
10883 It is common for a system to host a number of services. These may be started in several different fashions, each having different advantages.
10885 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.
10887 A generic startup script in `/usr/pkg/share/examples/rc.d` looks like:
10901 /usr/pkg/bin/foobar
10907 kill -9 `cat /var/run/foobar.pid`
10914 echo "Usage: `basename $0` {start|stop}" >&2
10928 <!-- XXX: I don't think we actually look in /usr/pkg/share/examples/rc.d -->
10930 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:
10934 # chmod 755 "FooBar.sh"
10936 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.
10938 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.
10940 **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.
10942 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.
10944 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.
10948 CategoryHandbook-configuration
10950 ## Configuring the cron Utility
10952 <!-- XXX: can't really comment on this. someone please revise it -->
10954 ***Contributed by Tom Rhodes. ***
10956 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.
10958 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.
10960 **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.
10962 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`.
10964 Let us take a look at the `/etc/crontab` file (the system crontab):
10968 # /etc/crontab - root's crontab for DragonFly
10978 PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin (2)
10986 #minute hour mday month wday who command (3)
10993 */5 * * * * root /usr/libexec/atrun (4)
10995 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.
10997 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.
10999 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.
11001 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.
11003 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.
11005 ### Installing a Crontab
11007 **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.
11009 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:
11013 % crontab crontab-file
11015 In this example, `crontab-file` is the filename of a `crontab` that was previously created.
11017 There is also an option to list installed `crontab` files: just pass the `-l` option to `crontab` and look over the output.
11019 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.
11021 If you later want to remove your user `crontab` completely, use `crontab` with the `-r` option.
11023 ## Using rc under DragonFly
11025 ***Contributed by Tom Rhodes. ***
11027 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:
11031 # /etc/rc.d/sshd restart
11033 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`:
11037 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.
11039 Another way to add services to the automatic startup/shutdown is to type, for example for `natd`,
11043 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:
11047 # /etc/rc.d/sshd forcerestart
11049 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:
11053 # /etc/rc.d/sshd rcvar
11059 **Note:** The second line (`# sshd`) is the output from the `rc.d` script, not a `root` prompt.
11061 To determine if a service is running, a `status` option is available. For instance to verify that `sshd` is actually started:
11065 # /etc/rc.d/sshd status
11067 sshd is running as pid 433.
11069 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.
11071 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.
11073 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:
11075 * `PROVIDE`: Specifies the services this file provides.
11077 * `REQUIRE`: Lists services which are required for this service. This file will run ***after*** the specified services.
11079 * `BEFORE`: Lists services which depend on this service. This file will run ***before*** the specified services.
11081 * 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.
11083 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.
11085 By using this method, an administrator can easily control system services without the hassle of ***runlevels*** like some other UNIX® operating systems.
11087 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.
11089 ### Using DragonFly's rcrun(8)
11091 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)
11093 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.
11095 The remaining commands are:
11098 **disable** | Sets the corresponding `_enable` variable in rc.conf(5) to ***NO*** and runs the stop command.
11099 **enable** | Sets the corresponding `_enable` variable in rc.conf(5) to ***YES*** and runs the start command.
11100 **list** | Shows the status of the specified scripts. If no argument is specified, the status of all scripts is shown. |
11104 To enable the [dntpd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=dntpd§ion=8) service, you can use:
11110 To check if [dntpd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=dntpd§ion=8) is running you can use the following command:
11118 To start [dntpd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=dntpd§ion=8):
11124 Running /etc/rc.d/dntpd start
11128 Restart and stop works the same way:
11144 If a service is not enabled in `/etc/rc.conf`, but you want it start anyway, execute the following:
11150 Running /etc/rc.d/dntpd forcestart
11157 <tablestyle="width:100%"> [(1)](configtuning-rcng.html#AEN4751) | Previously this was used to define *BSD dependent features.
11162 ## Setting Up Network Interface Cards
11164 ***Contributed by Marc Fonvieille. ***
11166 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.
11168 ### Locating the Correct Driver
11170 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.
11172 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.
11174 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:
11178 dc0: <82c169 PNIC 10/100BaseTX> port 0xa000-0xa0ff mem 0xd3800000-0xd38
11180 000ff irq 15 at device 11.0 on pci0
11182 dc0: Ethernet address: 00:a0:cc:da:da:da
11184 miibus0: <MII bus> on dc0
11186 ukphy0: <Generic IEEE 802.3u media interface> on miibus0
11188 ukphy0: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto
11190 dc1: <82c169 PNIC 10/100BaseTX> port 0x9800-0x98ff mem 0xd3000000-0xd30
11192 000ff irq 11 at device 12.0 on pci0
11194 dc1: Ethernet address: 00:a0:cc:da:da:db
11196 miibus1: <MII bus> on dc1
11198 ukphy1: <Generic IEEE 802.3u media interface> on miibus1
11200 ukphy1: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto
11202 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.
11204 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.
11206 ### Configuring the Network Card
11208 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.
11210 To display the configuration for the network interfaces on your system, enter the following command:
11216 dc0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
11218 inet 192.168.1.3 netmask 0xffffff00 broadcast 192.168.1.255
11220 ether 00:a0:cc:da:da:da
11222 media: Ethernet autoselect (100baseTX <full-duplex>)
11226 dc1: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
11228 inet 10.0.0.1 netmask 0xffffff00 broadcast 10.0.0.255
11230 ether 00:a0:cc:da:da:db
11232 media: Ethernet 10baseT/UTP
11236 lp0: flags=8810<POINTOPOINT,SIMPLEX,MULTICAST> mtu 1500
11238 lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> mtu 16384
11240 inet 127.0.0.1 netmask 0xff000000
11242 tun0: flags=8010<POINTOPOINT,MULTICAST> mtu 1500
11244 **Note:** Note that entries concerning IPv6 (`inet6` etc.) were omitted in this example.
11246 In this example, the following devices were displayed:
11248 * `dc0`: The first Ethernet interface
11250 * `dc1`: The second Ethernet interface
11252 * `lp0`: The parallel port interface
11254 * `lo0`: The loopback device
11256 * `tun0`: The tunnel device used by **ppp**
11258 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.
11260 In this example, the `dc0` device is up and running. The key indicators are:
11262 1. `UP` means that the card is configured and ready.
11264 1. The card has an Internet (`inet`) address (in this case `192.168.1.3`).
11266 1. It has a valid subnet mask (`netmask`; `0xffffff00` is the same as `255.255.255.0`).
11268 1. It has a valid broadcast address (in this case, `192.168.1.255`).
11270 1. The MAC address of the card (`ether`) is `00:a0:cc:da:da:da`
11272 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.
11274 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.
11276 If the [ifconfig(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=ifconfig§ion=8) output had shown something similar to:
11280 dc0: flags=8843<BROADCAST,SIMPLEX,MULTICAST> mtu 1500
11282 ether 00:a0:cc:da:da:da
11284 it would indicate the card has not been configured.
11286 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.
11290 # ifconfig dc0 inet 192.168.1.3 netmask 255.255.255.0
11292 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.
11294 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:
11298 ifconfig_dc0="inet 192.168.1.3 netmask 255.255.255.0"
11300 ifconfig_dc1="inet 10.0.0.1 netmask 255.255.255.0 media 10baseT/UTP"
11302 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`.
11304 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.
11306 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`.
11308 ### Testing and Troubleshooting
11310 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.
11312 Once the system has been rebooted, you should test the network interfaces.
11314 #### Testing the Ethernet Card
11316 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.
11318 First test the local interface:
11322 % ping -c5 192.168.1.3
11324 PING 192.168.1.3 (192.168.1.3): 56 data bytes
11326 64 bytes from 192.168.1.3: icmp_seq#0 ttl64 time=0.082 ms
11328 64 bytes from 192.168.1.3: icmp_seq#1 ttl64 time=0.074 ms
11330 64 bytes from 192.168.1.3: icmp_seq#2 ttl64 time=0.076 ms
11332 64 bytes from 192.168.1.3: icmp_seq#3 ttl64 time=0.108 ms
11334 64 bytes from 192.168.1.3: icmp_seq#4 ttl64 time=0.076 ms
11338 --- 192.168.1.3 ping statistics ---
11340 5 packets transmitted, 5 packets received, 0% packet loss
11342 round-trip min/avg/max/stddev = 0.074/0.083/0.108/0.013 ms
11344 Now we have to ping another machine on the LAN:
11348 % ping -c5 192.168.1.2
11350 PING 192.168.1.2 (192.168.1.2): 56 data bytes
11352 64 bytes from 192.168.1.2: icmp_seq#0 ttl64 time=0.726 ms
11354 64 bytes from 192.168.1.2: icmp_seq#1 ttl64 time=0.766 ms
11356 64 bytes from 192.168.1.2: icmp_seq#2 ttl64 time=0.700 ms
11358 64 bytes from 192.168.1.2: icmp_seq#3 ttl64 time=0.747 ms
11360 64 bytes from 192.168.1.2: icmp_seq#4 ttl64 time=0.704 ms
11364 --- 192.168.1.2 ping statistics ---
11366 5 packets transmitted, 5 packets received, 0% packet loss
11368 round-trip min/avg/max/stddev = 0.700/0.729/0.766/0.025 ms
11370 You could also use the machine name instead of `192.168.1.2` if you have set up the `/etc/hosts` file.
11372 #### Troubleshooting
11374 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.
11376 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.
11378 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.
11380 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.
11382 ***`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].
11384 ***`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.
11386 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.
11390 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.
11392 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`.
11394 An alias entry for the interface `fxp0` looks like:
11398 ifconfig_fxp0_alias0="inet xxx.xxx.xxx.xxx netmask xxx.xxx.xxx.xxx"
11400 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.
11402 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`).
11404 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`.
11406 The following entries configure the adapter correctly for this arrangement:
11410 ifconfig_fxp0="inet 10.1.1.1 netmask 255.255.255.0"
11412 ifconfig_fxp0_alias0="inet 10.1.1.2 netmask 255.255.255.255"
11414 ifconfig_fxp0_alias1="inet 10.1.1.3 netmask 255.255.255.255"
11416 ifconfig_fxp0_alias2="inet 10.1.1.4 netmask 255.255.255.255"
11418 ifconfig_fxp0_alias3="inet 10.1.1.5 netmask 255.255.255.255"
11420 ifconfig_fxp0_alias4="inet 202.0.75.17 netmask 255.255.255.240"
11422 ifconfig_fxp0_alias5="inet 202.0.75.18 netmask 255.255.255.255"
11424 ifconfig_fxp0_alias6="inet 202.0.75.19 netmask 255.255.255.255"
11426 ifconfig_fxp0_alias7="inet 202.0.75.20 netmask 255.255.255.255"
11430 CategoryHandbook-configuration
11432 ## Configuration Files
11436 There are a number of directories in which configuration information is kept. These include:
11439 `/etc` | Generic system configuration information; data here is system-specific.
11440 `/etc/defaults` | Default versions of system configuration files.
11441 `/etc/mail` | Extra [sendmail(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=sendmail§ion=8) configuration, other MTA configuration files.
11442 `/etc/ppp` | Configuration for both user- and kernel-ppp programs.
11443 `/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.
11444 `/usr/local/etc` | Configuration files for installed applications. May contain per-application subdirectories.
11445 `/usr/local/etc/rc.d` | Start/stop scripts for installed applications.
11446 `/var/db` | Automatically generated system-specific database files, such as the package database, the locate database, and so on |
11452 #### /etc/resolv.conf
11454 `/etc/resolv.conf` dictates how DragonFly's resolver accesses the Internet Domain Name System (DNS).
11456 The most common entries to `resolv.conf` are:
11459 `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.
11460 `search` | Search list for hostname lookup. This is normally determined by the domain of the local hostname.
11461 `domain` | The local domain name. |
11465 A typical `resolv.conf`:
11471 nameserver 147.11.1.11
11473 nameserver 147.11.100.30
11475 **Note:** Only one of the `search` and `domain` options should be used.
11477 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.
11481 `/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.
11491 # This file should contain the addresses and aliases
11493 # for local hosts that share this file.
11495 # In the presence of the domain name service or NIS, this file may
11497 # not be consulted at all; see /etc/nsswitch.conf for the resolution order.
11503 ::1 localhost localhost.my.domain myname.my.domain
11505 127.0.0.1 localhost localhost.my.domain myname.my.domain
11509 # Imaginary network.
11511 #10.0.0.2 myname.my.domain myname
11513 #10.0.0.3 myfriend.my.domain myfriend
11517 # According to RFC 1918, you can use the following IP networks for
11519 # private nets which will never be connected to the Internet:
11523 # 10.0.0.0 - 10.255.255.255
11525 # 172.16.0.0 - 172.31.255.255
11527 # 192.168.0.0 - 192.168.255.255
11531 # In case you want to be able to connect to the Internet, you need
11533 # real official assigned numbers. PLEASE PLEASE PLEASE do not try
11535 # to invent your own network numbers but instead get one from your
11537 # network provider (if any) or from the Internet Registry (ftp to
11539 # rs.internic.net, directory `/templates').
11543 `/etc/hosts` takes on the simple format of:
11547 [Internet address] [official hostname] [alias1] [alias2] ...
11553 10.0.0.1 myRealHostname.example.com myRealHostname foobar1 foobar2
11555 Consult [hosts(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=hosts§ion=5) for more information.
11557 ### Log File Configuration
11561 `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.
11569 # Spaces ARE valid field separators in this file. However,
11571 # other *nix-like systems still insist on using tabs as field
11573 # separators. If you are sharing this file between systems, you
11575 # may want to use only tabs as field separators here.
11577 # Consult the syslog.conf(5) manual page.
11580 *.err;kern.debug;auth.notice;mail.crit /dev/console
11582 *.notice;kern.debug;lpr.info;mail.crit;news.err /var/log/messages
11584 security.* /var/log/security
11586 mail.info /var/log/maillog
11588 lpr.info /var/log/lpd-errs
11590 cron.* /var/log/cron
11595 *.notice;news.err root
11601 # uncomment this to log all writes to /dev/console to /var/log/console.log
11603 #console.info /var/log/console.log
11605 # uncomment this to enable logging of all log messages to /var/log/all.log
11607 #*.* /var/log/all.log
11609 # uncomment this to enable logging to a remote log host named loghost
11613 # uncomment these if you're running inn
11615 # news.crit /var/log/news/news.crit
11617 # news.err /var/log/news/news.err
11619 # news.notice /var/log/news/news.notice
11624 *.* /var/log/slip.log
11629 *.* /var/log/ppp.log
11631 Consult the [syslog.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=syslog.conf§ion=5) manual page for more information.
11633 #### newsyslog.conf
11635 `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.
11637 `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.
11641 # configuration file for newsyslog
11647 # filename [owner:group] mode count size when [ZB] [/pid_file] [sig_num]
11649 /var/log/cron 600 3 100 * Z
11651 /var/log/amd.log 644 7 100 * Z
11653 /var/log/kerberos.log 644 7 100 * Z
11655 /var/log/lpd-errs 644 7 100 * Z
11657 /var/log/maillog 644 7 * @T00 Z
11659 /var/log/sendmail.st 644 10 * 168 B
11661 /var/log/messages 644 5 100 * Z
11663 /var/log/all.log 600 7 * @T00 Z
11665 /var/log/slip.log 600 3 100 * Z
11667 /var/log/ppp.log 600 3 100 * Z
11669 /var/log/security 600 10 100 * Z
11671 /var/log/wtmp 644 3 * @01T05 B
11673 /var/log/daily.log 640 7 * @T00 Z
11675 /var/log/weekly.log 640 5 1 $W6D0 Z
11677 /var/log/monthly.log 640 12 * $M1D0 Z
11679 /var/log/console.log 640 5 100 * Z
11681 Consult the [newsyslog(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=newsyslog§ion=8) manual page for more information.
11685 `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.
11687 A sample `sysctl.conf` turning off logging of fatal signal exits and letting Linux programs know they are really running under DragonFly:
11691 kern.logsigexit=0 # Do not log fatal signal exits (e.g. sig 11)
11693 compat.linux.osname=DragonFly
11695 compat.linux.osrelease=4.3-STABLE
11702 ## Tuning with sysctl
11704 [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).
11706 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.
11708 To view all readable variables:
11714 To read a particular variable, for example, `kern.maxproc`:
11718 % sysctl kern.maxproc
11722 To set a particular variable, use the intuitive `***variable***`=`***value***` syntax:
11726 # sysctl kern.maxfiles=5000
11728 kern.maxfiles: 2088 -< 5000
11730 Settings of sysctl variables are usually either strings, numbers, or booleans (a boolean being `1` for yes or a `0` for no).
11732 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].
11734 ### sysctl(8) Read-only
11736 ***Contributed by Tom Rhodes. ***
11738 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.
11740 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:
11744 cbb0: Could not map register memory
11746 device_probe_and_attach: cbb0 attach returned 12
11748 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.
11750 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.
11754 ### Sysctl Variables
11756 #### `vfs.vmiodirenable`
11758 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.
11760 #### `vfs.write_behind`
11762 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.
11764 #### `vfs.hirunningspace`
11766 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.
11768 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.
11770 #### `vm.swap_idle_enabled`
11772 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.
11776 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.
11778 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.
11780 For more information, please see [ata(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=ata§ion=4) manual page.
11782 <!-- XXX: add some more sysctls, e.g. relating to AHCI, nata, ... -->
11786 **Note** that soft updates are only available on UFS.
11788 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:
11792 # tunefs -n enable /filesystem
11794 # tunefs -n disable /filesystem
11796 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.
11798 **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).
11800 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.
11802 #### More Details about Soft Updates
11803 <!-- XXX: consider axing this section -->
11805 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.)
11807 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`).
11809 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.
11811 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.
11813 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.
11815 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.
11817 ## Tuning Kernel Limits
11819 ### File/Process Limits
11821 #### `kern.maxfiles`
11823 <!-- XXX: revise this section; someone who knows about it -->
11825 `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.
11827 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.
11829 `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.
11831 **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.
11833 #### `kern.ipc.somaxconn`
11835 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.
11839 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.
11841 <!-- XXX: mention kern.ipc.mbufs sysctl -->
11843 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.
11845 **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.
11847 #### `net.inet.ip.portrange.*`
11849 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.
11851 #### TCP Bandwidth Delay Product
11852 <!-- XXX: Revise this stuff, I'm not familiar with it -->
11854 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.
11856 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).
11858 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.
11860 ## Adding Swap Space
11861 <!-- XXX: swapcache -->
11863 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.
11865 ### Swap on a New Hard Drive
11867 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.
11869 ### Swapping over NFS
11871 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.
11875 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.
11877 **Example 6-1. Creating a Swapfile**
11879 1. Be certain that your kernel configuration includes the vnode driver. It is ***not*** in recent versions of `GENERIC`.
11883 pseudo-device vn 1 #Vnode driver (turns a file into a device)
11887 1. Create a swapfile (`/usr/swap0`):
11891 # dd if=/dev/zero of=/usr/swap0 bs=1024k count=64
11895 1. Set proper permissions on (`/usr/swap0`):
11899 # chmod 0600 /usr/swap0
11903 1. Enable the swap file in `/etc/rc.conf`:
11907 swapfile="/usr/swap0" # Set to name of swapfile if aux swapfile desired.
11911 1. Reboot the machine or to enable the swap file immediately, type:
11915 # vnconfig -e /dev/vn0b /usr/swap0 swap
11919 ## Power and Resource Management
11921 ***Written by Hiten Pandya and Tom Rhodes. ***
11923 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.
11925 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.
11929 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).
11931 ### Shortcomings of Advanced Power Management (APM)
11933 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.
11935 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.
11937 ***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.
11939 The DragonFly APM driver is documented in the [apm(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=apm§ion=4) manual page.
11941 ### Configuring ACPI
11943 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.
11945 **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.
11947 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:
11953 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.
11955 ## Using and Debugging DragonFly ACPI
11957 ***Written by Nate Lawson. With contributions from Peter Schultz and Tom Rhodes. ***
11959 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.
11961 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.
11963 ### Submitting Debugging Information
11965 **Note:** Before submitting a problem, be sure you are running the latest BIOS version and, if available, embedded controller firmware version.
11967 For those of you that want to submit a problem right away, please send the following information to [bugs](http://leaf.dragonflybsd.org/mailarchive/)
11969 * 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.
11971 * The dmesg output after ***boot `-v`***, including any error messages generated by you exercising the bug.
11973 * dmesg output from ***boot `-v`*** with ACPI disabled, if disabling it helps fix the problem.
11975 * Output from ***sysctl hw.acpi***. This is also a good way of figuring out what features your system offers.
11977 * 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:
11980 # acpidump -t -d > name-system.asl
11984 (Substitute your login name for `name` and manufacturer/model for `system`. Example: `njl-FooCo6000.asl`)
11988 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.
11990 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.
11992 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`.
11994 ### Common Problems
11996 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.
11998 #### Suspend/Resume
12000 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.
12002 Start by checking `sysctl` `hw.acpi` for the suspend-related items. Here are the results for my Thinkpad:
12004 hw.acpi.supported_sleep_state: S3 S4 S5
12008 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.
12010 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.
12012 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.
12014 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.
12016 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.
12018 <-- XXX: mention sensors somewhere; but not in this section -->
12020 #### System Hangs (temporary or permanent)
12022 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).
12024 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`.
12026 Your best hope when dealing with interrupt problems is to try disabling APIC support with `hint.apic.0.disabled="1"` in `loader.conf`.
12030 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.
12032 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.
12034 #### System Powers Up After Suspend or Shutdown
12036 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.
12038 #### Other Problems
12040 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.
12042 ### ASL, acpidump, and IASL
12043 <!-- XXX: IMHO all this crap about fixing your DSDT etc should be axed -->
12045 The most common problem is the BIOS vendors providing incorrect (or outright buggy!) bytecode. This is usually manifested by kernel console messages like this:
12049 ACPI-1287: *** Error: Method execution failed [\\_SB_.PCI0.LPC0.FIGD._STA] \\
12051 (Node 0xc3f6d160), AE_NOT_FOUND
12053 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.
12055 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:
12061 ### Fixing Your ASL
12063 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.
12065 Here is a list of common error messages, their cause, and how to fix them:
12067 #### OS dependencies
12069 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.
12071 #### Missing Return statements
12073 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.
12075 #### Overriding the Default AML
12077 After you customize `your.asl`, you will want to compile it, run:
12082 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.
12084 `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:
12088 acpi_dsdt_load="YES"
12090 acpi_dsdt_name="/boot/DSDT.aml"
12092 Be sure to copy your `DSDT.aml` to the `/boot` directory.
12094 ### Getting Debugging Output From ACPI
12096 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.
12098 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:
12102 # cd /sys/dev/acpica5 && make clean && make ACPI_DEBUG=1
12104 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.
12108 debug.acpi.layer="ACPI_ALL_COMPONENTS ACPI_ALL_DRIVERS"
12110 debug.acpi.level="ACPI_LV_ERROR"
12112 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`.
12116 More information about ACPI may be found in the following locations:
12118 * 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.)
12120 * The ACPI Mailing List Archives (FreeBSD) http://lists.freebsd.org/pipermail/freebsd-acpi/
12122 * The old ACPI Mailing List Archives (FreeBSD) http://home.jp.FreeBSD.org/mail-list/acpi-jp/
12124 * The ACPI 2.0 Specification http://acpi.info/spec.htm
12126 * 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)
12128 * [DSDT debugging resource](http://www.cpqlinux.com/acpi-howto.html#fix_broken_dsdt). (Uses Compaq as an example but generally useful.)
12130 # The DragonFly virtual kernels
12133 ***Obtained from [vkernel(7)](http://leaf.dragonflybsd.org/cgi/web-man?command=vkernel§ion=7) written by Sascha Wildner, added by Matthias Schmidt***
12135 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.
12137 The vkernel architecture allows for running DragonFly kernels in userland.
12139 ## Supported devices
12141 A number of virtual device drivers exist to supplement the virtual kernel.
12143 <!-- XXX: why do they only support 16 devices? is this really true? -->
12147 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`.
12151 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.
12153 ### Network interface
12155 The vke driver supports up to 16 virtual network interfaces which are
12157 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.
12159 ## Setup a virtual kernel environment
12161 A couple of steps are necessary in order to prepare the system to build and run a virtual kernel.
12163 ### Setting up the filesystem
12165 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`:
12169 % mkdir /home/var.vkernel
12170 % ln -s /home/var.vkernel /var/vkernel
12172 Next, a filesystem image to be used by the virtual kernel has to be created and populated (assuming world has been built previously):
12174 # dd if=/dev/zero of=/var/vkernel/rootimg.01 bs=1m count=2048
12175 # vnconfig -c vn0 /var/vkernel/rootimg.01
12176 # disklabel -r -w vn0s0 auto
12177 # disklabel -e vn0s0 # add 'a' partition with fstype `4.2BSD' size could be '*'
12178 # newfs /dev/vn0s0a
12179 # mount /dev/vn0s0a /mnt
12181 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.
12183 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).
12186 # make installworld DESTDIR=/mnt
12188 # make distribution DESTDIR=/mnt
12190 Create a fstab file to let the vkernel find your image file.
12194 # echo '/dev/vkd0s0a / ufs rw 1 1' >/mnt/etc/fstab
12195 # echo 'proc /proc procfs rw 0 0' >>/mnt/etc/fstab
12197 Edit `/mnt/etc/ttys` and replace the console entry with the following line and turn off all other gettys.
12199 # console "/usr/libexec/getty Pc" cons25 on secure
12201 Then, unmount the disk.
12206 ### Compiling the virtual kernel
12208 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):
12212 # make -DNO_MODULES buildkernel KERNCONF=VKERNEL
12213 # make -DNO_MODULES installkernel KERNCONF=VKERNEL DESTDIR=/var/vkernel
12215 ### Enabling virtual kernel operation
12217 A special sysctl(8), `vm.vkernel_enable`, must be set to enable vkernel operation:
12219 # sysctl vm.vkernel_enable=1
12221 To make this change permanent, edit `/etc/sysctl.conf`
12223 ## Setup networking
12225 ### Configuring the network on the host system
12227 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:
12231 # kldload if_bridge.ko
12232 # kldload if_tap.ko
12233 # ifconfig bridge0 create
12234 # ifconfig bridge0 addm re0 # assuming re0 is the host's interface
12235 # ifconfig bridge0 up
12237 **Note** : You have to change `re0` to the interface of your host machine.
12242 ## Run a virtual kernel
12244 Finally, the virtual kernel can be run:
12247 # ./boot/kernel/kernel -m 64m -r /var/vkernel/rootimg.01 -I auto:bridge0
12249 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.
12251 # The DragonFly Booting Process
12256 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.
12258 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.
12260 After reading this chapter, you will know:
12262 * What the components of the DragonFly bootstrap system are, and how they interact.
12264 * The options you can give to the components in the DragonFly bootstrap to control the boot process.
12266 * The basics of [device.hints(5)](http://leaf.dragonflybsd.org/cgi/web-man?command#device.hints§ion5&manpath=FreeBSD+5.2-current).
12268 **x86 Only:** This chapter only describes the boot process for DragonFly running on x86 systems.
12270 ## The Booting Problem
12272 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?
12274 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***.
12276 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.
12278 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.)
12280 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`.
12282 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.
12284 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.
12286 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.
12290 ## The Boot Manager and Boot Stages
12292 ### The Boot Manager
12294 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** .
12296 **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:
12298 **Example 7-1. `boot0` Screenshot**
12316 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:
12320 # fdisk -B -b /boot/boot0 device
12322 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).
12324 **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:
12332 loader=/boot/chain.b
12336 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.
12338 ### Stage One, /boot/boot1, and Stage Two, /boot/boot2
12340 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).
12342 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`.
12344 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.
12346 `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`.
12348 `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.
12350 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.
12352 **Example 7-2. boot2 Screenshot**
12356 >> DragonFly/i386 BOOT
12358 Default: 0:ad(0,a)/boot/loader
12362 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):
12366 # disklabel -B diskslice
12368 where `***diskslice***` is the disk and slice you boot from, such as `ad0s1` for the first slice on the first IDE disk.
12370 ### Stage Three, `/boot/loader`
12372 The loader is the final stage of the three-stage bootstrap, and is located on the file system, usually as `/boot/loader`.
12374 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.
12376 #### Loader Program Flow
12378 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.
12380 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.
12382 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.
12384 #### Loader Built-In Commands
12386 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).
12388 * 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.
12390 * boot [`***-options***`] [`***kernelname***`]: Immediately proceeds to boot the kernel, with the given options, if any, and with the kernel name given, if it is.
12392 *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`.
12394 * help [`***topic***`]: Shows help messages read from `/boot/loader.help`. If the topic given is `index`, then the list of available topics is given.
12396 * 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.
12398 * 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.
12400 * 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.
12402 * lsdev [`-v`]: Lists all of the devices from which it may be possible to load modules. If `-v` is specified, more details are printed.
12404 * lsmod [`-v`]: Displays loaded modules. If `-v` is specified, more details are shown.
12406 * more `***filename***`: Displays the files specified, with a pause at each `LINES` displayed.
12408 * reboot: Immediately reboots the system.
12410 * set `***variable***`, set `***variable***`=`***value***`: Sets the loader's environment variables.
12412 * unload: Removes all loaded modules.
12414 #### Loader Examples
12416 Here are some practical examples of loader usage:
12418 * To simply boot your usual kernel, but in single-user mode:
12426 * To unload your usual kernel and modules, and then load just your old (or another) kernel:
12436 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).
12438 **Note:** Use the following to load your usual modules with another kernel:
12444 set kernel="kernel.old"
12450 * To load a kernel configuration script (an automated script which does the things you would normally do in the kernel boot-time configurator):
12454 load -t userconfig_script /boot/kernel.conf
12460 ## Kernel Interaction During Boot
12462 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.
12464 ### Kernel Boot Flags
12466 Here are the more common boot flags:
12468 `-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
12470 **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.
12472 ## Init: Process Control Initialization
12474 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`.
12476 ### Automatic Reboot Sequence
12478 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.
12480 ### Single-User Mode
12482 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`.
12484 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).
12486 If the system `console` is set to `insecure` in `/etc/ttys`, then the system prompts for the `root` password before initiating single-user mode.
12488 ***'Example 7-3. An Insecure Console in `/etc/ttys`***'
12492 # name getty type status comments
12496 # If console is marked "insecure", then init will ask for the root password
12498 # when going to single-user mode.
12500 console none unknown off insecure
12502 **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`.
12504 ### Multi-User Mode
12506 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.
12508 #### Resource Configuration (rc)
12510 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.
12512 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.
12514 ## Shutdown Sequence
12516 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.
12518 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.
12520 **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.
12522 <!-- this section needs the info about sernos and vfs.mountrootfrom or whatever it's called -->
12524 # Users and Basic Account Management
12526 ***Contributed by Neil Blakey-Milner. ***
12532 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.
12534 After reading this chapter, you will know:
12536 * The differences between the various user accounts on a DragonFly system.
12538 * How to add user accounts.
12540 * How to remove user accounts.
12542 * How to change account details, such as the user's full name, or preferred shell.
12544 * 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.
12546 * How to use groups to make account management easier.
12548 Before reading this chapter, you should:
12550 * Understand the basics of UNIX® and DragonFly ([Chapter 3](basics.html)).
12554 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.
12556 Every account on a DragonFly system has certain information associated with it to identify the account.
12558 * 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.
12560 * 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.
12562 * 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.
12564 * Login class: Login classes are an extension to the group mechanism that provide additional flexibility when tailoring the system to different users.
12566 * 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.
12568 * 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.
12570 * 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.
12572 * 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.
12574 * 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.
12576 There are three main types of accounts: the Superuser, system users and 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.
12578 ## The Superuser Account
12580 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.
12582 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.
12584 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.
12586 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.
12590 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.
12592 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.
12594 `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.
12598 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.
12600 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.
12602 Each user can set up their own environment to accommodate their use of the system, by using alternate shells, editors, key bindings, and language.
12604 ## Modifying Accounts
12606 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.
12610 [adduser(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=adduser§ion=8) | The recommended command-line application for adding new users.
12611 [rmuser(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rmuser§ion=8) | The recommended command-line application for removing users.
12612 [chpass(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=chpass§ion=1) | A flexible tool to change user database information.
12613 [passwd(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=passwd§ion=1) | The simple command-line tool to change user passwords.
12614 [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. |
12620 [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.
12622 To create the initial configuration file, use `adduser -s -config_create`. 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.
12624 **Example 8-1. Configuring `adduser` and adding a user**
12630 Use option -silent if you don't want to see all warnings and questions.
12634 Check /etc/master.passwd
12638 Enter your default shell: csh date no sh tcsh zsh [sh]: zsh
12640 Your default shell is: zsh -> /usr/local/bin/zsh
12642 Enter your default HOME partition: [/home]:
12644 Copy dotfiles from: /usr/share/skel no [/usr/share/skel]:
12646 Send message from file: /etc/adduser.message no
12648 [/etc/adduser.message]: no
12650 Do not send message
12652 Use passwords (y/n) [y]: y
12656 Write your changes to /etc/adduser.conf? (y/n) [n]: y
12662 Don't worry about mistakes. I will give you the chance later to correct any input.
12664 Enter username [a-z0-9_-]: jru
12666 Enter full name []: J. Random User
12668 Enter shell csh date no sh tcsh zsh [zsh]:
12670 Enter home directory (full path) [/home/jru]:
12674 Enter login class: default []:
12676 Login group jru [jru]:
12678 Login group is ***jru***. Invite jru into other groups: guest no
12684 Enter password again []:
12692 Fullname: J. Random User
12704 Shell: /usr/local/bin/zsh
12708 Added user ***jru***
12710 Copy files from /usr/share/skel to /home/jru
12712 Add another user? (y/n) [y]: n
12718 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.)
12720 **Note:** The password you type in is not echoed, nor are asterisks displayed. Make sure you do not mistype the password twice.
12722 **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.
12726 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:
12728 1. Removes the user's [crontab(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=crontab§ion=1) entry (if any).
12730 1. Removes any [at(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=at§ion=1) jobs belonging to the user.
12732 1. Kills all processes owned by the user.
12734 1. Removes the user from the system's local password file.
12736 1. Removes the user's home directory (if it is owned by the user).
12738 1. Removes the incoming mail files belonging to the user from `/var/mail`.
12740 1. Removes all files owned by the user from temporary file storage areas such as `/tmp`.
12742 1. Finally, removes the username from all groups to which it belongs in `/etc/group`.
12744 **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).
12746 [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.
12748 By default, an interactive mode is used, which attempts to make sure you know what you are doing.
12750 **Example 8-2. `rmuser` Interactive Account Removal**
12756 Matching password entry:
12758 jru:*:1001:1001::0:0:J. Random User:/home/jru:/usr/local/bin/zsh
12760 Is this the entry you wish to remove? y
12762 Remove user's home directory (/home/jru)? y
12764 Updating password file, updating databases, done.
12766 Updating group file: trusted (removing group jru -- personal group is empty) done.
12768 Removing user's incoming mail file /var/mail/jru: done.
12770 Removing files belonging to jru from /tmp: done.
12772 Removing files belonging to jru from /var/tmp: done.
12774 Removing files belonging to jru from /var/tmp/vi.recover: done.
12780 [chpass(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=chpass§ion=1) changes user database information such as passwords, shells, and personal information.
12782 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).
12784 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.
12786 ***'Example 8-3. Interactive `chpass` by Superuser***'
12790 #Changing user database information for jru.
12798 Gid [# or name]: 1001
12800 Change [month day year]:
12802 Expire [month day year]:
12806 Home directory: /home/jru
12808 Shell: /usr/local/bin/zsh
12810 Full Name: J. Random User
12820 The normal user can change only a small subset of this information, and only for themselves.
12822 **Example 8-4. Interactive chpass by Normal User**
12826 #Changing user database information for jru.
12828 Shell: /usr/local/bin/zsh
12830 Full Name: J. Random User
12840 **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].
12844 [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.
12846 **Note:** To prevent accidental or unauthorized changes, the original password must be entered before a new password can be set.
12848 **Example 8-5. Changing Your Password**
12854 Changing local password for jru.
12860 Retype new password:
12862 passwd: updating the database...
12866 ***'Example 8-6. Changing Another User's Password as the Superuser***'
12872 Changing local password for jru.
12876 Retype new password:
12878 passwd: updating the database...
12882 **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.
12886 [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.
12891 <tablestyle#"width:100%"> 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. |
12897 <!-- XXX: check this section, I got the feeling there might be something outdated in it. I'm not familiar with it -->
12899 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.
12901 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].
12903 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.
12905 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).
12907 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).
12909 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)).
12911 * `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.
12913 * `cputime`: This is the maximum amount of CPU time a user's process may consume. Offending processes will be killed by the kernel.
12915 **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.
12917 * `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.
12919 * `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).
12921 * `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.
12923 * `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.
12925 * `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).
12927 * `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.
12929 * `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.
12931 There are a few other things to remember when setting resource limits. Following are some general tips, suggestions, and miscellaneous comments.
12933 * Processes started at system startup by `/etc/rc` are assigned to the `daemon` login class.
12935 * 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.
12937 * 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.
12939 * 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.
12941 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).
12943 ## Personalizing Users
12945 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).
12949 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.
12951 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.
12953 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:
12955 **Example 8-7. Adding a Group Using pw(8)**
12959 # pw groupadd teamtwo
12961 # pw groupshow teamtwo
12965 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.
12967 **Example 8-8. Adding Somebody to a Group Using pw(8)**
12971 # pw groupmod teamtwo -M jru
12973 # pw groupshow teamtwo
12977 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`.
12979 **Example 8-9. Using id(1) to Determine Group Membership**
12985 uid#1001(jru) gid1001(jru) groups=1001(jru), 1100(teamtwo)
12987 As you can see, `jru` is a member of the groups `jru` and `teamtwo`.
12989 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.
12991 # Configuring the DragonFly Kernel
12993 ***Updated and restructured by Jim Mock. Originally contributed by Jake Hamby.***
12999 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.
13001 After reading this chapter, you will know:
13003 * Why you might need to build a custom kernel.
13004 * How to write a kernel configuration file, or alter an existing configuration file.
13005 * How to use the kernel configuration file to create and build a new kernel.
13006 * How to install the new kernel.
13007 * How to troubleshoot if things go wrong.
13009 ## Why Build a Custom Kernel?
13011 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.
13013 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.
13015 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.
13017 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:
13019 * 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.
13021 * 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.
13023 * 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.
13025 ## Building and Installing a Custom Kernel
13027 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.
13029 ### Installing the Source
13031 If there is ***no*** `/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.
13033 The preferred way of installing the sources is:
13038 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:
13042 ### Your Custom Config File
13044 Next, move to the `config` directory and copy the `GENERIC` configuration file to the name you want to give your kernel. For example:
13046 # cd /usr/src/sys/config
13047 # cp GENERIC MYKERNEL
13049 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.
13051 **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.
13055 # cd /usr/src/sys/config
13056 # mkdir /root/kernels
13057 # cp GENERIC /root/kernels/MYKERNEL
13058 # ln -s /root/kernels/MYKERNEL
13060 **Note:** You must execute these and all of the following commands under the `root` account or you will get permission denied errors.
13062 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`.
13064 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.
13066 ### Building a Kernel - Full Source Tree
13068 **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.
13070 1. Change to the `/usr/src` directory.
13076 1. Compile the kernel.
13078 # make buildkernel KERNCONF=MYKERNEL
13080 1. Install the new kernel.
13082 # make installkernel KERNCONF=MYKERNEL
13086 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.
13088 ### Building a Kernel - Kernel Source Only
13090 When only the kernel source is installed, you need to change step 2, above, to this:
13093 # make nativekernel KERNCONF=MYKERNEL
13095 The other steps are the same.
13097 ### Running Your New Kernel
13099 The installer copies the new kernel and modules to `/boot/kernel/`, the kernel being `/boot/kernel/kernel` and the modules being `/boot/kernel/*.ko`. The old kernel and modules are moved to `/boot/kernel.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).
13101 **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.
13103 ## The Configuration File
13104 <!-- XXX: do we really want to mention all these million config options? -->
13105 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`.
13107 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`.
13115 # GENERIC -- Generic kernel configuration file for DragonFly/i386
13119 # Check the LINT configuration file in sys/config, for an
13121 # exhaustive list of options.
13125 # $DragonFly: src/sys/config/GENERIC,v 1.56 2007/12/26 14:02:36 sephe Exp $
13127 The following are the mandatory keywords required in ***every*** kernel you build:
13133 This is the machine architecture. It must be `i386` at the moment. Support for `amd64` will be added in the future.
13145 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.
13151 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).
13157 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.
13159 (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.
13161 **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`].
13165 # Floating point support - do not disable.
13167 device npx0 at nexus? port IO_NPX irq 13
13169 `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.
13173 # Pseudo devices - the number indicates how many units to allocate.
13175 pseudo-device loop # Network loopback
13177 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***.
13179 Everything that follows is more or less optional. See the notes underneath or next to each option for more information.
13183 #makeoptions DEBUG=-g #Build kernel with gdb(1) debug symbols
13185 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).
13189 options MATH_EMULATE #Support for x87 emulation
13191 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.
13193 **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.
13197 options INET #InterNETworking
13199 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.
13203 options INET6 #IPv6 communications protocols
13205 This enables the IPv6 communication protocols.
13209 options FFS #Berkeley Fast Filesystem
13211 options FFS_ROOT #FFS usable as root device [keep this!]
13213 This is the basic hard drive Filesystem. Leave it in if you boot from the hard disk.
13217 options UFS_DIRHASH #Improve performance on big directories
13219 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.
13223 options SOFTUPDATES #Enable FFS Soft Updates support
13225 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.
13229 options MFS #Memory Filesystem
13231 options MD_ROOT #MD is a potential root device
13233 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`:
13237 /dev/ad1s2b /tmp mfs rw 0 0
13239 Now you simply need to either reboot, or run the command `mount /tmp`.
13243 options NFS #Network Filesystem
13245 options NFS_ROOT #NFS usable as root device, NFS required
13247 The network Filesystem. Unless you plan to mount partitions from a UNIX® file server over TCP/IP, you can comment these out.
13251 options MSDOSFS #MSDOS Filesystem
13253 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).
13257 options CD9660 #ISO 9660 Filesystem
13259 options CD9660_ROOT #CD-ROM usable as root, CD9660 required
13261 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.
13265 options PROCFS #Process filesystem
13267 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. ***
13271 Compatibility with 4.3BSD. Leave this in; some programs will act strangely if you comment this out.
13275 options SCSI_DELAY=5000 #Delay (in ms) before probing SCSI
13277 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.
13281 options UCONSOLE #Allow users to grab the console
13283 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.
13287 options USERCONFIG #boot -c editor
13289 This option allows you to boot the configuration editor from the boot menu.
13293 options VISUAL_USERCONFIG #visual boot -c editor
13295 This option allows you to boot the visual configuration editor from the boot menu.
13299 options KTRACE #ktrace(1) support
13301 This enables kernel process tracing, which is useful in debugging.
13305 options SYSVSHM #SYSV-style shared memory
13307 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.
13311 options SYSVSEM #SYSV-style semaphores
13313 Support for System V semaphores. Less commonly used but only adds a few hundred bytes to the kernel.
13317 options SYSVMSG #SYSV-style message queues
13319 Support for System V messages. Again, only adds a few hundred bytes to the kernel.
13321 **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.
13325 options P1003_1B #Posix P1003_1B real-time extensions
13327 options _KPOSIX_PRIORITY_SCHEDULING
13329 Real-time extensions added in the 1993 POSIX®. Certain applications in the ports collection use these (such as **StarOffice™** ).
13333 options ICMP_BANDLIM #Rate limit bad replies
13335 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.
13339 # To make an SMP kernel, the next two are needed
13341 #options SMP # Symmetric MultiProcessor Kernel
13343 #options APIC_IO # Symmetric (APIC) I/O
13345 The above are both required for SMP support.
13351 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`.
13357 Include this if you have an EISA motherboard. This enables auto-detection and configuration support for all devices on the EISA bus.
13363 Include this if you have a PCI motherboard. This enables auto-detection of PCI cards and gatewaying from the PCI to ISA bus.
13369 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.
13375 device fdc0 at isa? port IO_FD1 irq 6 drq 2
13377 device fd0 at fdc0 drive 0
13379 device fd1 at fdc0 drive 1
13381 This is the floppy drive controller. `fd0` is the `A:` floppy drive, and `fd1` is the `B:` drive.
13387 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.
13391 device atadisk # ATA disk drives
13393 This is needed along with `device ata` for ATA disk drives.
13397 device atapicd # ATAPI CDROM drives
13399 This is needed along with `device ata` for ATAPI CDROM drives.
13403 device atapifd # ATAPI floppy drives
13405 This is needed along with `device ata` for ATAPI floppy drives.
13409 device atapist # ATAPI tape drives
13411 This is needed along with `device ata` for ATAPI tape drives.
13415 options ATA_STATIC_ID #Static device numbering
13417 This makes the controller number static (like the old driver) or else the device numbers are dynamically allocated.
13421 # ATA and ATAPI devices
13423 device ata0 at isa? port IO_WD1 irq 14
13425 device ata1 at isa? port IO_WD2 irq 15
13427 Use the above for older, non-PCI systems.
13433 device ahb # EISA AHA1742 family
13435 device ahc # AHA2940 and onboard AIC7xxx devices
13437 device amd # AMD 53C974 (Teckram DC-390(T))
13439 device dpt # DPT Smartcache - See LINT for options!
13441 device isp # Qlogic family
13443 device ncr # NCR/Symbios Logic
13445 device sym # NCR/Symbios Logic (newer chipsets)
13447 device adv0 at isa?
13453 device aha0 at isa?
13455 device aic0 at isa?
13457 SCSI controllers. Comment out any you do not have in your system. If you have an IDE only system, you can remove these altogether.
13463 device scbus # SCSI bus (required)
13465 device da # Direct Access (disks)
13467 device sa # Sequential Access (tape etc)
13471 device pass # Passthrough device (direct SCSI
13475 SCSI peripherals. Again, comment out any you do not have, or if you have only IDE hardware, you can remove them completely.
13477 **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.
13483 device ida # Compaq Smart RAID
13485 device amr # AMI MegaRAID
13487 device mlx # Mylex DAC960 family
13489 Supported RAID controllers. If you do not have any of these, you can comment them out or remove them.
13493 # atkbdc0 controls both the keyboard and the PS/2 mouse
13495 device atkbdc0 at isa? port IO_KBD
13497 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`).
13501 device atkbd0 at atkbdc? irq 1
13503 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.
13507 device psm0 at atkbdc? irq 12
13509 Use this device if your mouse plugs into the PS/2 mouse port.
13513 device vga0 at isa?
13515 The video card driver.
13519 # splash screen/screen saver
13521 pseudo-device splash
13523 Splash screen at start up! Screen savers require this too.
13527 # syscons is the default console driver, resembling an SCO console
13531 `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.
13535 # Enable this and PCVT_FREEBSD for pcvt vt220 compatible console driver
13537 #device vt0 at isa?
13539 #options XSERVER # support for X server on a vt console
13541 #options FAT_CURSOR # start with block cursor
13543 # If you have a ThinkPAD, uncomment this along with the rest of the PCVT lines
13545 #options PCVT_SCANSET=2 # IBM keyboards are non-std
13547 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.
13551 # Power management support (see LINT for more options)
13553 device apm0 at nexus? disable flags 0x20 # Advanced Power Management
13555 Advanced Power Management support. Useful for laptops.
13559 # PCCARD (PCMCIA) support
13563 device pcic0 at isa? irq 10 port 0x3e0 iomem 0xd0000
13565 device pcic1 at isa? irq 11 port 0x3e2 iomem 0xd4000 disable
13567 PCMCIA support. You want this if you are using a laptop.
13571 # Serial (COM) ports
13573 device sio0 at isa? port IO_COM1 flags 0x10 irq 4
13575 device sio1 at isa? port IO_COM2 irq 3
13577 device sio2 at isa? disable port IO_COM3 irq 5
13579 device sio3 at isa? disable port IO_COM4 irq 9
13581 These are the four serial ports referred to as COM1 through COM4 in the MS-DOS/Windows® world.
13583 **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.
13585 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.
13591 device ppc0 at isa? irq 7
13593 This is the ISA-bus parallel port interface.
13597 device ppbus # Parallel port bus (required)
13599 Provides support for the parallel port bus.
13603 device lpt # Printer
13605 Support for parallel port printers.
13607 **Note:** All three of the above are required to enable parallel printer support.
13611 device plip # TCP/IP over parallel
13613 This is the driver for the parallel network interface.
13617 device ppi # Parallel port interface device
13619 The general-purpose I/O (***geek port) + IEEE1284 I/O.
13623 #device vpo # Requires scbus and da
13625 This is for an Iomega Zip drive. It requires `scbus` and `da` support. Best performance is achieved with ports in EPP 1.9 mode.
13629 # PCI Ethernet NICs.
13631 device de # DEC/Intel DC21x4x (Tulip)
13633 device fxp # Intel EtherExpress PRO/100B (82557, 82558)
13635 device tx # SMC 9432TX (83c170 EPIC)
13637 device vx # 3Com 3c590, 3c595 (Vortex)
13639 device wx # Intel Gigabit Ethernet Card (Wiseman)
13641 Various PCI network card drivers. Comment out or remove any of these not present in your system.
13645 # PCI Ethernet NICs that use the common MII bus controller code.
13647 device miibus # MII bus support
13649 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.
13653 device dc # DEC/Intel 21143 and various workalikes
13655 device rl # RealTek 8129/8139
13657 device sf # Adaptec AIC-6915 (Starfire)
13659 device sis # Silicon Integrated Systems SiS 900/SiS 7016
13661 device ste # Sundance ST201 (D-Link DFE-550TX)
13663 device tl # Texas Instruments ThunderLAN
13665 device vr # VIA Rhine, Rhine II
13667 device wb # Winbond W89C840F
13669 device xl # 3Com 3c90x (Boomerang, Cyclone)
13671 Drivers that use the MII bus controller code.
13675 # ISA Ethernet NICs.
13677 device ed0 at isa? port 0x280 irq 10 iomem 0xd8000
13683 # WaveLAN/IEEE 802.11 wireless NICs. Note: the WaveLAN/IEEE really
13685 # exists only as a PCMCIA device, so there is no ISA attachment needed
13687 # and resources will always be dynamically assigned by the pccard code.
13691 # Aironet 4500/4800 802.11 wireless NICs. Note: the declaration below will
13693 # work for PCMCIA and PCI cards, as well as ISA cards set to ISA PnP
13695 # mode (the factory default). If you set the switches on your ISA
13697 # card for a manually chosen I/O address and IRQ, you must specify
13699 # those parameters here.
13703 # The probe order of these is presently determined by i386/isa/isa_compat.c.
13705 device ie0 at isa? port 0x300 irq 10 iomem 0xd0000
13707 device fe0 at isa? port 0x300
13709 device le0 at isa? port 0x300 irq 5 iomem 0xd0000
13711 device lnc0 at isa? port 0x280 irq 10 drq 0
13713 device cs0 at isa? port 0x300
13715 device sn0 at isa? port 0x300 irq 10
13717 # requires PCCARD (PCMCIA) support to be activated
13719 #device xe0 at isa?
13721 ISA Ethernet drivers. See `/usr/src/sys/config/LINT` for which cards are supported by which driver.
13725 pseudo-device ether # Ethernet support
13727 `ether` is only needed if you have an Ethernet card. It includes generic Ethernet protocol code.
13731 pseudo-device sl 1 # Kernel SLIP
13733 `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.
13737 pseudo-device ppp 1 # Kernel PPP
13739 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. .
13743 device tun # Packet tunnel.
13745 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.
13749 pseudo-device pty # Pseudo-ttys (telnet etc)
13751 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. ***
13755 Memory disk pseudo-devices.
13759 pseudo-device gif # IPv6 and IPv4 tunneling
13761 This implements IPv6 over IPv4 tunneling, IPv4 over IPv6 tunneling, IPv4 over IPv4 tunneling, and IPv6 over IPv6 tunneling.
13765 pseudo-device faith # IPv6-to-IPv4 relaying (translation)
13767 This pseudo-device captures packets that are sent to it and diverts them to the IPv4/IPv6 translation daemon.
13771 # The `bpf' device enables the Berkeley Packet Filter.
13773 # Be aware of the administrative consequences of enabling this!
13775 pseudo-device bpf # Berkeley packet filter
13777 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.
13779 **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.
13785 #device uhci # UHCI PCI->USB interface
13787 #device ohci # OHCI PCI->USB interface
13789 #device usb # USB Bus (required)
13791 #device ugen # Generic
13793 #device uhid # ***Human Interface Devices***
13795 #device ukbd # Keyboard
13797 #device ulpt # Printer
13799 #device umass # Disks/Mass storage - Requires scbus and da
13801 #device ums # Mouse
13803 # USB Ethernet, requires mii
13805 #device aue # ADMtek USB ethernet
13807 #device cue # CATC USB ethernet
13809 #device kue # Kawasaki LSI USB ethernet
13811 Support for various USB devices.
13813 For more information and additional devices supported by DragonFly, see `/usr/src/sys/i386/conf/LINT`.
13818 <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. |
13824 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.
13826 These nodes are created automatically once devfs is mounted, which happens manually for the root `/dev` during boot, just after the root mount.
13828 ## If Something Goes Wrong
13830 **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:
13832 % chflags noschg /boot/kernel
13835 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.
13837 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:
13841 % chflags schg /boot/kernel
13844 There are five categories of trouble that can occur when building a custom kernel. They are:
13846 * `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.
13848 * `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.
13850 * 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.
13852 * 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.
13854 * 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.
13857 ***Much of this chapter has been taken from the security(7) manual page by Matthew Dillon. ***
13863 This chapter will provide a basic introduction to system security concepts, some general good rules of thumb, and some advanced topics under DragonFly. A lot of the topics covered here can be applied to system and Internet security in general as well. The Internet is no longer a ***friendly*** place in which everyone wants to be your kind neighbor. Securing your system is imperative to protect your data, intellectual property, time, and much more from the hands of hackers and the like.
13865 DragonFly provides an array of utilities and mechanisms to ensure the integrity and security of your system and network.
13867 After reading this chapter, you will know:
13869 * Basic system security concepts, in respect to DragonFly.
13871 * About the various crypt mechanisms available in DragonFly, such as DES and MD5.
13873 * How to set up one-time password authentication.
13875 * How to create firewalls using IPFW.
13877 * How to configure IPsec and create a VPN between DragonFly/Windows® machines.
13879 * How to configure and use **OpenSSH** , DragonFly's SSH implementation.
13881 Before reading this chapter, you should:
13883 * Understand basic DragonFly and Internet concepts.
13891 Security is a function that begins and ends with the system administrator. While all BSD UNIX® multi-user systems have some inherent security, the job of building and maintaining additional security mechanisms to keep those users ***honest*** is probably one of the single largest undertakings of the sysadmin. Machines are only as secure as you make them, and security concerns are ever competing with the human necessity for convenience. UNIX systems, in general, are capable of running a huge number of simultaneous processes and many of these processes operate as servers -- meaning that external entities can connect and talk to them. As yesterday's mini-computers and mainframes become today's desktops, and as computers become networked and internetworked, security becomes an even bigger issue.
13893 Security is best implemented through a layered ***onion*** approach. In a nutshell, what you want to do is to create as many layers of security as are convenient and then carefully monitor the system for intrusions. You do not want to overbuild your security or you will interfere with the detection side, and detection is one of the single most important aspects of any security mechanism. For example, it makes little sense to set the `schg` flags (see [chflags(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#chflags§ion1)) on every system binary because while this may temporarily protect the binaries, it prevents an attacker who has broken in from making an easily detectable change that may result in your security mechanisms not detecting the attacker at all.
13895 System security also pertains to dealing with various forms of attack, including attacks that attempt to crash, or otherwise make a system unusable, but do not attempt to compromise the `root` account (***break root***). Security concerns can be split up into several categories:
13897 1. Denial of service attacks.
13899 1. User account compromises.
13901 1. Root compromise through accessible servers.
13903 1. Root compromise via user accounts.
13905 1. Backdoor creation.
13907 A denial of service attack is an action that deprives the machine of needed resources. Typically, DoS attacks are brute-force mechanisms that attempt to crash or otherwise make a machine unusable by overwhelming its servers or network stack. Some DoS attacks try to take advantage of bugs in the networking stack to crash a machine with a single packet. The latter can only be fixed by applying a bug fix to the kernel. Attacks on servers can often be fixed by properly specifying options to limit the load the servers incur on the system under adverse conditions. Brute-force network attacks are harder to deal with. A spoofed-packet attack, for example, is nearly impossible to stop, short of cutting your system off from the Internet. It may not be able to take your machine down, but it can saturate your Internet connection.
13909 A user account compromise is even more common than a DoS attack. Many sysadmins still run standard **telnetd** , **rlogind** , **rshd** , and **ftpd** servers on their machines. These servers, by default, do not operate over encrypted connections. The result is that if you have any moderate-sized user base, one or more of your users logging into your system from a remote location (which is the most common and convenient way to login to a system) will have his or her password sniffed. The attentive system admin will analyze his remote access logs looking for suspicious source addresses even for successful logins.
13911 One must always assume that once an attacker has access to a user account, the attacker can break `root`. However, the reality is that in a well secured and maintained system, access to a user account does not necessarily give the attacker access to `root`. The distinction is important because without access to `root` the attacker cannot generally hide his tracks and may, at best, be able to do nothing more than mess with the user's files, or crash the machine. User account compromises are very common because users tend not to take the precautions that sysadmins take.
13913 System administrators must keep in mind that there are potentially many ways to break `root` on a machine. The attacker may know the `root` password, the attacker may find a bug in a root-run server and be able to break `root` over a network connection to that server, or the attacker may know of a bug in a suid-root program that allows the attacker to break `root` once he has broken into a user's account. If an attacker has found a way to break `root` on a machine, the attacker may not have a need to install a backdoor. Many of the `root` holes found and closed to date involve a considerable amount of work by the attacker to cleanup after himself, so most attackers install backdoors. A backdoor provides the attacker with a way to easily regain `root` access to the system, but it also gives the smart system administrator a convenient way to detect the intrusion. Making it impossible for an attacker to install a backdoor may actually be detrimental to your security, because it will not close off the hole the attacker found to break in the first place.
13915 Security remedies should always be implemented with a multi-layered ***onion peel*** approach and can be categorized as follows:
13917 1. Securing `root` and staff accounts.
13919 1. Securing `root` -- root-run servers and suid/sgid binaries.
13921 1. Securing user accounts.
13923 1. Securing the password file.
13925 1. Securing the kernel core, raw devices, and filesystems.
13927 1. Quick detection of inappropriate changes made to the system.
13931 The next section of this chapter will cover the above bullet items in greater depth.
13935 CategoryHandbook-security
13937 ## Securing DragonFly
13939 **Command vs. Protocol:** Throughout this document, we will use **bold** text to refer to a command or application. This is used for instances such as ssh, since it is a protocol as well as command.
13941 The sections that follow will cover the methods of securing your DragonFly system that were mentioned in the [last section](security-intro.html) of this chapter.
13943 ### Securing the root Account and Staff Accounts
13945 First off, do not bother securing staff accounts if you have not secured the `root` account. Most systems have a password assigned to the `root` account. The first thing you do is assume that the password is ***always*** compromised. This does not mean that you should remove the password. The password is almost always necessary for console access to the machine. What it does mean is that you should not make it possible to use the password outside of the console or possibly even with the [su(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#su§ion1) command. For example, make sure that your pty's are specified as being insecure in the `/etc/ttys` file so that direct `root` logins via `telnet` or `rlogin` are disallowed. If using other login services such as **sshd** , make sure that direct `root` logins are disabled there as well. You can do this by editing your `/etc/ssh/sshd_config` file, and making sure that `PermitRootLogin` is set to `NO`. Consider every access method -- services such as FTP often fall through the cracks. Direct `root` logins should only be allowed via the system console.
13947 Of course, as a sysadmin you have to be able to get to `root`, so we open up a few holes. But we make sure these holes require additional password verification to operate. One way to make `root` accessible is to add appropriate staff accounts to the `wheel` group (in `/etc/group`). The staff members placed in the `wheel` group are allowed to `su` to `root`. You should never give staff members native `wheel` access by putting them in the `wheel` group in their password entry. Staff accounts should be placed in a `staff` group, and then added to the `wheel` group via the `/etc/group` file. Only those staff members who actually need to have `root` access should be placed in the `wheel` group. While having the `wheel` mechanism is better than having nothing at all, it is not necessarily the safest option.
13949 An indirect way to secure staff accounts, and ultimately `root` access is to use an alternative login access method and do what is known as ***starring*** out the encrypted password for the staff accounts. Using the [vipw(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#vipw§ion8) command, one can replace each instance of an encrypted password with a single `*` character. This command will update the `/etc/master.passwd` file and user/password database to disable password-authenticated logins.
13951 A staff account entry such as:
13955 foobar:R9DT/Fa1/LV9U:1000:1000::0:0:Foo Bar:/home/foobar:/usr/local/bin/tcsh
13957 Should be changed to this:
13961 foobar:*:1000:1000::0:0:Foo Bar:/home/foobar:/usr/local/bin/tcsh
13963 This change will prevent normal logins from occurring, since the encrypted password will never match `*`. With this done, staff members must use another mechanism to authenticate themselves such as [ssh(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ssh§ion=1&manpath=OpenBSD+3.3) using a public/private key pair. When using a public/private key pair with ssh, one must generally secure the machine used to login ***from*** (typically one's workstation). An additional layer of protection can be added to the key pair by password protecting the key pair when creating it with [ssh-keygen(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ssh-keygen§ion=1). Being able to ***star*** out the passwords for staff accounts also guarantees that staff members can only login through secure access methods that you have set up. This forces all staff members to use secure, encrypted connections for all of their sessions, which closes an important hole used by many intruders: sniffing the network from an unrelated, less secure machine.
13965 The more indirect security mechanisms also assume that you are logging in from a more restrictive server to a less restrictive server. For example, if your main box is running all sorts of servers, your workstation should not be running any. In order for your workstation to be reasonably secure you should run as few servers as possible, up to and including no servers at all, and you should run a password-protected screen blanker. Of course, given physical access to a workstation an attacker can break any sort of security you put on it. This is definitely a problem that you should consider, but you should also consider the fact that the vast majority of break-ins occur remotely, over a network, from people who do not have physical access to your workstation or servers.
13967 ### Securing Root-run Servers and SUID/SGID Binaries
13969 The prudent sysadmin only runs the servers he needs to, no more, no less. Be aware that third party servers are often the most bug-prone. For example, running an old version of **imapd** or **popper** is like giving a universal `root` ticket out to the entire world. Never run a server that you have not checked out carefully. Many servers do not need to be run as `root`. For example, the **ntalk** , **comsat** , and **finger** daemons can be run in special user ***sandboxes***. A sandbox is not perfect, unless you go through a large amount of trouble, but the onion approach to security still stands: If someone is able to break in through a server running in a sandbox, they still have to break out of the sandbox. The more layers the attacker must break through, the lower the likelihood of his success. Root holes have historically been found in virtually every server ever run as `root`, including basic system servers. If you are running a machine through which people only login via **sshd** and never login via **telnetd** or **rshd** or **rlogind** , then turn off those services!
13971 DragonFly now defaults to running **ntalkd** , **comsat** , and **finger** in a sandbox. Another program which may be a candidate for running in a sandbox is [named(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#named§ion8). `/etc/defaults/rc.conf` includes the arguments necessary to run **named** in a sandbox in a commented-out form. Depending on whether you are installing a new system or upgrading an existing system, the special user accounts used by these sandboxes may not be installed. The prudent sysadmin would research and implement sandboxes for servers whenever possible.
13973 There are a number of other servers that typically do not run in sandboxes: **sendmail** , **popper** , **imapd** , **ftpd** , and others. There are alternatives to some of these, but installing them may require more work than you are willing to perform (the convenience factor strikes again). You may have to run these servers as `root` and rely on other mechanisms to detect break-ins that might occur through them.
13975 The other big potential `root` holes in a system are the suid-root and sgid binaries installed on the system. Most of these binaries, such as **rlogin** , reside in `/bin`, `/sbin`, `/usr/bin`, or `/usr/sbin`. While nothing is 100% safe, the system-default suid and sgid binaries can be considered reasonably safe. Still, `root` holes are occasionally found in these binaries. A `root` hole was found in `Xlib` in 1998 that made **xterm** (which is typically suid) vulnerable. It is better to be safe than sorry and the prudent sysadmin will restrict suid binaries, that only staff should run, to a special group that only staff can access, and get rid of (`chmod 000`) any suid binaries that nobody uses. A server with no display generally does not need an **xterm** binary. Sgid binaries can be almost as dangerous. If an intruder can break an sgid-kmem binary, the intruder might be able to read `/dev/kmem` and thus read the encrypted password file, potentially compromising any passworded account. Alternatively an intruder who breaks group `kmem` can monitor keystrokes sent through pty's, including pty's used by users who login through secure methods. An intruder that breaks the `tty` group can write to almost any user's tty. If a user is running a terminal program or emulator with a keyboard-simulation feature, the intruder can potentially generate a data stream that causes the user's terminal to echo a command, which is then run as that user.
13977 ### Securing User Accounts
13979 User accounts are usually the most difficult to secure. While you can impose Draconian access restrictions on your staff and ***star*** out their passwords, you may not be able to do so with any general user accounts you might have. If you do have sufficient control, then you may win out and be able to secure the user accounts properly. If not, you simply have to be more vigilant in your monitoring of those accounts. Use of ssh for user accounts is more problematic, due to the extra administration and technical support required, but still a very good solution compared to a crypted password file.
13981 ### Securing the Password File
13983 The only sure fire way is to `*` out as many passwords as you can and use ssh for access to those accounts. Even though the encrypted password file (`/etc/spwd.db`) can only be read by `root`, it may be possible for an intruder to obtain read access to that file even if the attacker cannot obtain root-write access.
13985 Your security scripts should always check for and report changes to the password file (see the [Checking file integrity](securing-freebsd.html#SECURITY-INTEGRITY) section below).
13987 ### Securing the Kernel Core, Raw Devices, and Filesystems
13989 If an attacker breaks `root` he can do just about anything, but there are certain conveniences. For example, most modern kernels have a packet sniffing device driver built in. Under DragonFly it is called the `bpf` device. An intruder will commonly attempt to run a packet sniffer on a compromised machine. You do not need to give the intruder the capability and most systems do not have the need for the `bpf` device compiled in.
13991 But even if you turn off the `bpf` device, you still have `/dev/mem` and `/dev/kmem` to worry about. For that matter, the intruder can still write to raw disk devices. Also, there is another kernel feature called the module loader, [kldload(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#kldload§ion8). An enterprising intruder can use a KLD module to install his own `bpf` device, or other sniffing device, on a running kernel. To avoid these problems you have to run the kernel at a higher secure level, at least securelevel 1. The securelevel can be set with a `sysctl` on the `kern.securelevel` variable. Once you have set the securelevel to 1, write access to raw devices will be denied and special `chflags` flags, such as `schg`, will be enforced. You must also ensure that the `schg` flag is set on critical startup binaries, directories, and script files -- everything that gets run up to the point where the securelevel is set. This might be overdoing it, and upgrading the system is much more difficult when you operate at a higher secure level. You may compromise and run the system at a higher secure level but not set the `schg` flag for every system file and directory under the sun. Another possibility is to simply mount `/` and `/usr` read-only. It should be noted that being too Draconian in what you attempt to protect may prevent the all-important detection of an intrusion.
13993 ### Checking File Integrity: Binaries, Configuration Files, Etc.
13995 When it comes right down to it, you can only protect your core system configuration and control files so much before the convenience factor rears its ugly head. For example, using `chflags` to set the `schg` bit on most of the files in `/` and `/usr` is probably counterproductive, because while it may protect the files, it also closes a detection window. The last layer of your security onion is perhaps the most important -- detection. The rest of your security is pretty much useless (or, worse, presents you with a false sense of safety) if you cannot detect potential incursions. Half the job of the onion is to slow down the attacker, rather than stop him, in order to give the detection side of the equation a chance to catch him in the act.
13997 The best way to detect an incursion is to look for modified, missing, or unexpected files. The best way to look for modified files is from another (often centralized) limited-access system. Writing your security scripts on the extra-secure limited-access system makes them mostly invisible to potential attackers, and this is important. In order to take maximum advantage you generally have to give the limited-access box significant access to the other machines in the business, usually either by doing a read-only NFS export of the other machines to the limited-access box, or by setting up ssh key-pairs to allow the limited-access box to ssh to the other machines. Except for its network traffic, NFS is the least visible method -- allowing you to monitor the filesystems on each client box virtually undetected. If your limited-access server is connected to the client boxes through a switch, the NFS method is often the better choice. If your limited-access server is connected to the client boxes through a hub, or through several layers of routing, the NFS method may be too insecure (network-wise) and using ssh may be the better choice even with the audit-trail tracks that ssh lays.
13999 Once you give a limited-access box, at least read access to the client systems it is supposed to monitor, you must write scripts to do the actual monitoring. Given an NFS mount, you can write scripts out of simple system utilities such as [find(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#find§ion1) and [md5(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=md5§ion=1). It is best to physically md5 the client-box files at least once a day, and to test control files such as those found in `/etc` and `/usr/local/etc` even more often. When mismatches are found, relative to the base md5 information the limited-access machine knows is valid, it should scream at a sysadmin to go check it out. A good security script will also check for inappropriate suid binaries and for new or deleted files on system partitions such as `/` and `/usr`.
14001 When using ssh rather than NFS, writing the security script is much more difficult. You essentially have to `scp` the scripts to the client box in order to run them, making them visible, and for safety you also need to `scp` the binaries (such as find) that those scripts use. The **ssh** client on the client box may already be compromised. All in all, using ssh may be necessary when running over insecure links, but it is also a lot harder to deal with.
14003 A good security script will also check for changes to user and staff members access configuration files: `.rhosts`, `.shosts`, `.ssh/authorized_keys` and so forth... files that might fall outside the purview of the `MD5` check.
14005 If you have a huge amount of user disk space, it may take too long to run through every file on those partitions. In this case, setting mount flags to disallow suid binaries and devices on those partitions is a good idea. The `nodev` and `nosuid` options (see [mount(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#mount§ion8)) are what you want to look into. You should probably scan them anyway, at least once a week, since the object of this layer is to detect a break-in whether or not the break-in is effective.
14007 Process accounting (see [accton(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#accton§ion8)) is a relatively low-overhead feature of the operating system which might help as a post-break-in evaluation mechanism. It is especially useful in tracking down how an intruder has actually broken into a system, assuming the file is still intact after the break-in occurs.
14009 Finally, security scripts should process the log files, and the logs themselves should be generated in as secure a manner as possible -- remote syslog can be very useful. An intruder tries to cover his tracks, and log files are critical to the sysadmin trying to track down the time and method of the initial break-in. One way to keep a permanent record of the log files is to run the system console to a serial port and collect the information on a continuing basis through a secure machine monitoring the consoles.
14013 A little paranoia never hurts. As a rule, a sysadmin can add any number of security features, as long as they do not affect convenience, and can add security features that ***do*** affect convenience with some added thought. Even more importantly, a security administrator should mix it up a bit -- if you use recommendations such as those given by this document verbatim, you give away your methodologies to the prospective attacker who also has access to this document.
14015 ### Denial of Service Attacks
14017 This section covers Denial of Service attacks. A DoS attack is typically a packet attack. While there is not much you can do about modern spoofed packet attacks that saturate your network, you can generally limit the damage by ensuring that the attacks cannot take down your servers.
14019 1. Limiting server forks.
14021 1. Limiting springboard attacks (ICMP response attacks, ping broadcast, etc.).
14023 1. Kernel Route Cache.
14025 A common DoS attack is against a forking server that attempts to cause the server to eat processes, file descriptors, and memory, until the machine dies. **inetd** (see [inetd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#inetd§ion8)) has several options to limit this sort of attack. It should be noted that while it is possible to prevent a machine from going down, it is not generally possible to prevent a service from being disrupted by the attack. Read the **inetd** manual page carefully and pay specific attention to the `-c`, `-C`, and `-R` options. Note that spoofed-IP attacks will circumvent the `-C` option to **inetd** , so typically a combination of options must be used. Some standalone servers have self-fork-limitation parameters.
14027 **Sendmail** has its `-OMaxDaemonChildren` option, which tends to work much better than trying to use sendmail's load limiting options due to the load lag. You should specify a `MaxDaemonChildren` parameter, when you start **sendmail** , high enough to handle your expected load, but not so high that the computer cannot handle that number of **sendmails** without falling on its face. It is also prudent to run sendmail in queued mode (`-ODeliveryMode=queued`) and to run the daemon (`sendmail -bd`) separate from the queue-runs (`sendmail -q15m`). If you still want real-time delivery you can run the queue at a much lower interval, such as `-q1m`, but be sure to specify a reasonable `MaxDaemonChildren` option for ***that*** sendmail to prevent cascade failures.
14029 **Syslogd** can be attacked directly and it is strongly recommended that you use the `-s` option whenever possible, and the `-a` option otherwise.
14031 You should also be fairly careful with connect-back services such as **tcpwrapper** s reverse-identd, which can be attacked directly. You generally do not want to use the reverse-ident feature of **tcpwrappers** for this reason.
14033 It is a very good idea to protect internal services from external access by firewalling them off at your border routers. The idea here is to prevent saturation attacks from outside your LAN, not so much to protect internal services from network-based `root` compromise. Always configure an exclusive firewall, i.e., firewall everything ***except*** ports A, B, C, D, and M-Z. This way you can firewall off all of your low ports except for certain specific services such as **named** (if you are primary for a zone), **ntalkd** , **sendmail** , and other Internet-accessible services. If you try to configure the firewall the other way -- as an inclusive or permissive firewall, there is a good chance that you will forget to ***close*** a couple of services, or that you will add a new internal service and forget to update the firewall. You can still open up the high-numbered port range on the firewall, to allow permissive-like operation, without compromising your low ports. Also take note that DragonFly allows you to control the range of port numbers used for dynamic binding, via the various `net.inet.ip.portrange` `sysctl`'s (`sysctl -a | fgrep portrange`), which can also ease the complexity of your firewall's configuration. For example, you might use a normal first/last range of 4000 to 5000, and a hiport range of 49152 to 65535, then block off everything under 4000 in your firewall (except for certain specific Internet-accessible ports, of course).
14035 Another common DoS attack is called a springboard attack -- to attack a server in a manner that causes the server to generate responses which overloads the server, the local network, or some other machine. The most common attack of this nature is the ***ICMP ping broadcast attack***. The attacker spoofs ping packets sent to your LAN's broadcast address with the source IP address set to the actual machine they wish to attack. If your border routers are not configured to stomp on ping's to broadcast addresses, your LAN winds up generating sufficient responses to the spoofed source address to saturate the victim, especially when the attacker uses the same trick on several dozen broadcast addresses over several dozen different networks at once. Broadcast attacks of over a hundred and twenty megabits have been measured. A second common springboard attack is against the ICMP error reporting system. By constructing packets that generate ICMP error responses, an attacker can saturate a server's incoming network and cause the server to saturate its outgoing network with ICMP responses. This type of attack can also crash the server by running it out of mbuf's, especially if the server cannot drain the ICMP responses it generates fast enough. The DragonFly kernel has a new kernel compile option called `ICMP_BANDLIM` which limits the effectiveness of these sorts of attacks. The last major class of springboard attacks is related to certain internal **inetd** services such as the udp echo service. An attacker simply spoofs a UDP packet with the source address being server A's echo port, and the destination address being server B's echo port, where server A and B are both on your LAN. The two servers then bounce this one packet back and forth between each other. The attacker can overload both servers and their LANs simply by injecting a few packets in this manner. Similar problems exist with the internal **chargen** port. A competent sysadmin will turn off all of these inetd-internal test services.
14037 Spoofed packet attacks may also be used to overload the kernel route cache. Refer to the `net.inet.ip.rtexpire`, `rtminexpire`, and `rtmaxcache` `sysctl` parameters. A spoofed packet attack that uses a random source IP will cause the kernel to generate a temporary cached route in the route table, viewable with `netstat -rna | fgrep W3`. These routes typically timeout in 1600 seconds or so. If the kernel detects that the cached route table has gotten too big it will dynamically reduce the `rtexpire` but will never decrease it to less than `rtminexpire`. There are two problems:
14039 1. The kernel does not react quickly enough when a lightly loaded server is suddenly attacked.
14041 1. The `rtminexpire` is not low enough for the kernel to survive a sustained attack.
14043 If your servers are connected to the Internet via a T3 or better, it may be prudent to manually override both `rtexpire` and `rtminexpire` via [sysctl(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#sysctl§ion8). Never set either parameter to zero (unless you want to crash the machine). Setting both parameters to two seconds should be sufficient to protect the route table from attack.
14045 ## DES, MD5, and Crypt
14047 ***Parts rewritten and updated by Bill Swingle. ***
14049 Every user on a UNIX® system has a password associated with their account. It seems obvious that these passwords need to be known only to the user and the actual operating system. In order to keep these passwords secret, they are encrypted with what is known as a ***one-way hash***, that is, they can only be easily encrypted but not decrypted. In other words, what we told you a moment ago was obvious is not even true: the operating system itself does not ***really*** know the password. It only knows the ***encrypted*** form of the password. The only way to get the ***plain-text*** password is by a brute force search of the space of possible passwords.
14051 Unfortunately the only secure way to encrypt passwords when UNIX came into being was based on DES, the Data Encryption Standard. This was not such a problem for users resident in the US, but since the source code for DES could not be exported outside the US, DragonFly had to find a way to both comply with US law and retain compatibility with all the other UNIX variants that still used DES.
14053 The solution was to divide up the encryption libraries so that US users could install the DES libraries and use DES but international users still had an encryption method that could be exported abroad. This is how DragonFly came to use MD5 as its default encryption method. MD5 is believed to be more secure than DES, so installing DES is offered primarily for compatibility reasons.
14055 ### Recognizing Your Crypt Mechanism
14057 `libcrypt.a` provides a configurable password authentication hash library. Currently the library supports DES, MD5, Blowfish, SHA256, and SHA512 hash functions. By default DragonFly uses SHA256 to encrypt passwords.
14059 It is pretty easy to identify which encryption method DragonFly is set up to use. Examining the encrypted passwords in the `/etc/master.passwd` file is one way. Passwords encrypted with the MD5 hash are longer than those encrypted with the DES hash and also begin with the characters `$1$`. Passwords starting with `$2a$` are encrypted with the Blowfish hash function. DES password strings do not have any particular identifying characteristics, but they are shorter than MD5 passwords, and are coded in a 64-character alphabet which does not include the `$` character, so a relatively short string which does not begin with a dollar sign is very likely a DES password.
14061 The password format used for new passwords is controlled by the `passwd_format` login capability in `/etc/login.conf`, which takes values of `des`, `md5` or `blf`. See the [login.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command#login.conf&section5) manual page for more information about login capabilities.
14063 ## One-time Passwords
14065 S/Key is a one-time password scheme based on a one-way hash function. DragonFly uses the MD4 hash for compatibility but other systems have used MD5 and DES-MAC. S/Key ia part of the FreeBSD base system, and is also used on a growing number of other operating systems. S/Key is a registered trademark of Bell Communications Research, Inc.
14067 There are three different sorts of passwords which we will discuss below. The first is your usual UNIX® style password; we will call this a ***UNIX password***. The second sort is the one-time password which is generated by the S/Key `key` program or the OPIE [opiekey(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#opiekey§ion1) program and accepted by the `keyinit` or [opiepasswd(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=opiepasswd§ion=1) programs and the login prompt; we will call this a ***one-time password***. The final sort of password is the secret password which you give to the `key`/`opiekey` programs (and sometimes the `keyinit`/`opiepasswd` programs) which it uses to generate one-time passwords; we will call it a ***secret password*** or just unqualified ***password***.
14069 The secret password does not have anything to do with your UNIX password; they can be the same but this is not recommended. S/Key and OPIE secret passwords are not limited to eight characters like old UNIX passwords[(1)](#FTN.AEN8429), they can be as long as you like. Passwords of six or seven word long phrases are fairly common. For the most part, the S/Key or OPIE system operates completely independently of the UNIX password system.
14071 Besides the password, there are two other pieces of data that are important to S/Key and OPIE. One is what is known as the ***seed*** or ***key***, consisting of two letters and five digits. The other is what is called the ***iteration count***, a number between 1 and 100. S/Key creates the one-time password by concatenating the seed and the secret password, then applying the MD4/MD5 hash as many times as specified by the iteration count and turning the result into six short English words. These six English words are your one-time password. The authentication system (primarily PAM) keeps track of the last one-time password used, and the user is authenticated if the hash of the user-provided password is equal to the previous password. Because a one-way hash is used it is impossible to generate future one-time passwords if a successfully used password is captured; the iteration count is decremented after each successful login to keep the user and the login program in sync. When the iteration count gets down to 1, S/Key and OPIE must be reinitialized.
14073 There are three programs involved in each system which we will discuss below. The `key` and `opiekey` programs accept an iteration count, a seed, and a secret password, and generate a one-time password or a consecutive list of one-time passwords. The `keyinit` and `opiepasswd` programs are used to initialize S/Key and OPIE respectively, and to change passwords, iteration counts, or seeds; they take either a secret passphrase, or an iteration count, seed, and one-time password. The `keyinfo` and `opieinfo` programs examine the relevant credentials files (`/etc/skeykeys` or `/etc/opiekeys`) and print out the invoking user's current iteration count and seed.
14075 There are four different sorts of operations we will cover. The first is using `keyinit` or `opiepasswd` over a secure connection to set up one-time-passwords for the first time, or to change your password or seed. The second operation is using `keyinit` or `opiepasswd` over an insecure connection, in conjunction with `key` or `opiekey` over a secure connection, to do the same. The third is using `key`/`opiekey` to log in over an insecure connection. The fourth is using `key` or `opiekey` to generate a number of keys which can be written down or printed out to carry with you when going to some location without secure connections to anywhere.
14077 ### Secure Connection Initialization
14079 To initialize S/Key for the first time, change your password, or change your seed while logged in over a secure connection (e.g., on the console of a machine or via **ssh** ), use the `keyinit` command without any parameters while logged in as yourself:
14087 Reminder - Only use this method if you are directly connected.
14089 If you are using telnet or rlogin exit with no password and use keyinit -s.
14091 Enter secret password:
14093 Again secret password:
14097 ID unfurl s/key is 99 to17757
14099 DEFY CLUB PRO NASH LACE SOFT
14101 For OPIE, `opiepasswd` is used instead:
14107 [grimreaper] ~ $ opiepasswd -f -c
14111 Only use this method from the console; NEVER from remote. If you are using
14113 telnet, xterm, or a dial-in, type ^C now or exit with no password.
14115 Then run opiepasswd without the -c parameter.
14117 Using MD5 to compute responses.
14119 Enter new secret pass phrase:
14121 Again new secret pass phrase:
14123 ID unfurl OTP key is 499 to4268
14125 MOS MALL GOAT ARM AVID COED
14127 At the Enter new secret pass phrase: or Enter secret password: prompts, you should enter a password or phrase. Remember, this is not the password that you will use to login with, this is used to generate your one-time login keys. The ***ID*** line gives the parameters of your particular instance: your login name, the iteration count, and seed. When logging in the system will remember these parameters and present them back to you so you do not have to remember them. The last line gives the particular one-time password which corresponds to those parameters and your secret password; if you were to re-login immediately, this one-time password is the one you would use.
14129 ### Insecure Connection Initialization
14131 To initialize or change your secret password over an insecure connection, you will need to already have a secure connection to some place where you can run `key` or `opiekey`; this might be in the form of a desk accessory on a Macintosh®, or a shell prompt on a machine you trust. You will also need to make up an iteration count (100 is probably a good value), and you may make up your own seed or use a randomly-generated one. Over on the insecure connection (to the machine you are initializing), use the `keyinit -s` command:
14141 Reminder you need the 6 English words from the key command.
14143 Enter sequence count from 1 to 9999: 100
14145 Enter new key [default to17759]:
14149 s/key access password:
14151 s/key access password:CURE MIKE BANE HIM RACY GORE
14153 For OPIE, you need to use `opiepasswd`:
14163 You need the response from an OTP generator.
14165 Old secret pass phrase:
14167 otp-md5 498 to4268 ext
14169 Response: GAME GAG WELT OUT DOWN CHAT
14171 New secret pass phrase:
14175 Response: LINE PAP MILK NELL BUOY TROY
14179 ID mark OTP key is 499 gr4269
14181 LINE PAP MILK NELL BUOY TROY
14183 To accept the default seed (which the `keyinit` program confusingly calls a `key`), press **Return** . Then before entering an access password, move over to your secure connection or S/Key desk accessory, and give it the same parameters:
14189 Reminder - Do not use this program while logged in via telnet or rlogin.
14191 Enter secret password: <secret password>
14193 CURE MIKE BANE HIM RACY GORE
14199 % opiekey 498 to4268
14201 Using the MD5 algorithm to compute response.
14203 Reminder: Don't use opiekey from telnet or dial-in sessions.
14205 Enter secret pass phrase:
14207 GAME GAG WELT OUT DOWN CHAT
14209 Now switch back over to the insecure connection, and copy the one-time password generated over to the relevant program.
14211 ### Generating a Single One-time Password
14213 Once you have initialized S/Key, when you login you will be presented with a prompt like this:
14217 % telnet example.com
14221 Connected to example.com
14223 Escape character is '^]'.
14227 DragonFly/i386 (example.com) (ttypa)
14231 login: <username>
14241 % telnet example.com
14245 Connected to example.com
14247 Escape character is '^]'.
14251 DragonFly/i386 (example.com) (ttypa)
14255 login: <username>
14257 otp-md5 498 gr4269 ext
14261 As a side note, the S/Key and OPIE prompts have a useful feature (not shown here): if you press **Return** at the password prompt, the prompter will turn echo on, so you can see what you are typing. This can be extremely useful if you are attempting to type in a password by hand, such as from a printout.
14263 At this point you need to generate your one-time password to answer this login prompt. This must be done on a trusted system that you can run `key` or `opiekey` on. (There are versions of these for DOS, Windows® and Mac OS® as well.) They need both the iteration count and the seed as command line options. You can cut-and-paste these right from the login prompt on the machine that you are logging in to.
14265 On the trusted system:
14271 Reminder - Do not use this program while logged in via telnet or rlogin.
14273 Enter secret password:
14275 WELD LIP ACTS ENDS ME HAAG
14281 % opiekey 498 to4268
14283 Using the MD5 algorithm to compute response.
14285 Reminder: Don't use opiekey from telnet or dial-in sessions.
14287 Enter secret pass phrase:
14289 GAME GAG WELT OUT DOWN CHAT
14291 Now that you have your one-time password you can continue logging in:
14295 login: <username>
14299 Password: <return to enable echo>
14303 Password [echo on]: WELD LIP ACTS ENDS ME HAAG
14305 Last login: Tue Mar 21 11:56:41 from 10.0.0.2 ...
14307 ### Generating Multiple One-time Passwords
14309 Sometimes you have to go places where you do not have access to a trusted machine or secure connection. In this case, it is possible to use the `key` and `opiekey` commands to generate a number of one-time passwords beforehand to be printed out and taken with you. For example:
14313 % key -n 5 30 zz99999
14315 Reminder - Do not use this program while logged in via telnet or rlogin.
14317 Enter secret password: <secret password>
14319 26: SODA RUDE LEA LIND BUDD SILT
14321 27: JILT SPY DUTY GLOW COWL ROT
14323 28: THEM OW COLA RUNT BONG SCOT
14325 29: COT MASH BARR BRIM NAN FLAG
14327 30: CAN KNEE CAST NAME FOLK BILK
14333 % opiekey -n 5 30 zz99999
14335 Using the MD5 algorithm to compute response.
14337 Reminder: Don't use opiekey from telnet or dial-in sessions.
14339 Enter secret pass phrase: <secret password>
14341 26: JOAN BORE FOSS DES NAY QUIT
14343 27: LATE BIAS SLAY FOLK MUCH TRIG
14345 28: SALT TIN ANTI LOON NEAL USE
14347 29: RIO ODIN GO BYE FURY TIC
14349 30: GREW JIVE SAN GIRD BOIL PHI
14351 The `-n 5` requests five keys in sequence, the `30` specifies what the last iteration number should be. Note that these are printed out in ***reverse*** order of eventual use. If you are really paranoid, you might want to write the results down by hand; otherwise you can cut-and-paste into `lpr`. Note that each line shows both the iteration count and the one-time password; you may still find it handy to scratch off passwords as you use them.
14353 ### Restricting Use of UNIX® Passwords
14355 S/Key can place restrictions on the use of UNIX passwords based on the host name, user name, terminal port, or IP address of a login session. These restrictions can be found in the configuration file `/etc/skey.access`. The [skey.access(5)](http://leaf.dragonflybsd.org/cgi/web-man?command#skey.access§ion5) manual page has more information on the complete format of the file and also details some security cautions to be aware of before depending on this file for security.
14357 If there is no `/etc/skey.access` file (this is the default), then all users will be allowed to use UNIX passwords. If the file exists, however, then all users will be required to use S/Key unless explicitly permitted to do otherwise by configuration statements in the `skey.access` file. In all cases, UNIX passwords are permitted on the console.
14359 Here is a sample `skey.access` configuration file which illustrates the three most common sorts of configuration statements:
14363 permit internet 192.168.0.0 255.255.0.0
14369 The first line (`permit internet`) allows users whose IP source address (which is vulnerable to spoofing) matches the specified value and mask, to use UNIX passwords. This should not be considered a security mechanism, but rather, a means to remind authorized users that they are using an insecure network and need to use S/Key for authentication.
14371 The second line (`permit user`) allows the specified username, in this case `fnord`, to use UNIX passwords at any time. Generally speaking, this should only be used for people who are either unable to use the `key` program, like those with dumb terminals, or those who are uneducable.
14373 The third line (`permit port`) allows all users logging in on the specified terminal line to use UNIX passwords; this would be used for dial-ups.
14375 Here is a sample `opieaccess` file:
14379 permit 192.168.0.0 255.255.0.0
14381 This line allows users whose IP source address (which is vulnerable to spoofing) matches the specified value and mask, to use UNIX passwords at any time.
14383 If no rules in `opieaccess` are matched, the default is to deny non-OPIE logins.
14388 |<tablestyle="width:100%"> [one-time-passwords.html#AEN8429 (1)] | Under DragonFly the standard login password may be up to 128 characters in length. |
14394 CategoryHandbook-security
14398 ***Contributed by Gary Palmer and Alex Nash. ***
14400 Firewalls are an area of increasing interest for people who are connected to the Internet, and are even finding applications on private networks to provide enhanced security. This section will hopefully explain what firewalls are, how to use them, and how to use the facilities provided in the DragonFly kernel to implement them.
14402 **Note:** People often think that having a firewall between your internal network and the ***Big Bad Internet*** will solve all your security problems. It may help, but a poorly set up firewall system is more of a security risk than not having one at all. A firewall can add another layer of security to your systems, but it cannot stop a really determined cracker from penetrating your internal network. If you let internal security lapse because you believe your firewall to be impenetrable, you have just made the crackers job that much easier.
14404 ### What Is a Firewall?
14406 There are currently two distinct types of firewalls in common use on the Internet today. The first type is more properly called a ***packet filtering router***. This type of firewall utilizes a multi-homed machine and a set of rules to determine whether to forward or block individual packets. A multi-homed machine is simply a device with multiple network interfaces. The second type, known as a ***proxy server***, relies on daemons to provide authentication and to forward packets, possibly on a multi-homed machine which has kernel packet forwarding disabled.
14408 Sometimes sites combine the two types of firewalls, so that only a certain machine (known as a ***bastion host***) is allowed to send packets through a packet filtering router onto an internal network. Proxy services are run on the bastion host, which are generally more secure than normal authentication mechanisms.
14410 DragonFly comes with a kernel packet filter (known as IPFW), which is what the rest of this section will concentrate on. Proxy servers can be built on DragonFly from third party software, but there is such a variety of proxy servers available that it would be impossible to cover them in this section.
14412 #### Packet Filtering Routers
14414 A router is a machine which forwards packets between two or more networks. A packet filtering router is programmed to compare each packet to a list of rules before deciding if it should be forwarded or not. Most modern IP routing software includes packet filtering functionality that defaults to forwarding all packets. To enable the filters, you need to define a set of rules.
14416 To decide whether a packet should be passed on, the firewall looks through its set of rules for a rule which matches the contents of the packet's headers. Once a match is found, the rule action is obeyed. The rule action could be to drop the packet, to forward the packet, or even to send an ICMP message back to the originator. Only the first match counts, as the rules are searched in order. Hence, the list of rules can be referred to as a ***rule chain***.
14418 The packet-matching criteria varies depending on the software used, but typically you can specify rules which depend on the source IP address of the packet, the destination IP address, the source port number, the destination port number (for protocols which support ports), or even the packet type (UDP, TCP, ICMP, etc).
14422 Proxy servers are machines which have had the normal system daemons ( **telnetd** , **ftpd** , etc) replaced with special servers. These servers are called ***proxy servers***, as they normally only allow onward connections to be made. This enables you to run (for example) a proxy **telnet** server on your firewall host, and people can **telnet** in to your firewall from the outside, go through some authentication mechanism, and then gain access to the internal network (alternatively, proxy servers can be used for signals coming from the internal network and heading out).
14424 Proxy servers are normally more secure than normal servers, and often have a wider variety of authentication mechanisms available, including ***one-shot*** password systems so that even if someone manages to discover what password you used, they will not be able to use it to gain access to your systems as the password expires immediately after the first use. As they do not actually give users access to the host machine, it becomes a lot more difficult for someone to install backdoors around your security system.
14426 Proxy servers often have ways of restricting access further, so that only certain hosts can gain access to the servers. Most will also allow the administrator to specify which users can talk to which destination machines. Again, what facilities are available depends largely on what proxy software you choose.
14428 ### Firewall options in DragonFlyBSD
14430 DragonFlyBSD inherited the IPFW firewall (versions 1 and 2) when it forked from FreeBSD. Pretty soon after though, we imported the new pf packet filter that the OpenBSD developers created from scratch. It is a cleaner code base and is now the recommended solution for firewalling DragonFly. Keep in mind that the PF version in DragonFly is not in sync with OpenBSD's PF code. We have not yet incorporated the improvements made in PF over the last few years, but we have some improvements of our own. IPFW is still and will remain supported for the forseeable future; it has some features not yet available in PF.
14432 A copy of the OpenBSD PF user's guide corresponding to the version of PF in DragonFly can be found in [[PFUsersGuide]].
14434 #### What Does IPFW Allow Me to Do?
14436 IPFW, the software supplied with DragonFly, is a packet filtering and accounting system which resides in the kernel, and has a user-land control utility, [ipfw(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#ipfw§ion8). Together, they allow you to define and query the rules used by the kernel in its routing decisions.
14438 There are two related parts to IPFW. The firewall section performs packet filtering. There is also an IP accounting section which tracks usage of the router, based on rules similar to those used in the firewall section. This allows the administrator to monitor how much traffic the router is getting from a certain machine, or how much WWW traffic it is forwarding, for example.
14440 As a result of the way that IPFW is designed, you can use IPFW on non-router machines to perform packet filtering on incoming and outgoing connections. This is a special case of the more general use of IPFW, and the same commands and techniques should be used in this situation.
14442 #### Enabling IPFW on DragonFly
14444 As the main part of the IPFW system lives in the kernel, you will need to add one or more options to your kernel configuration file, depending on what facilities you want, and recompile your kernel. See "Reconfiguring your Kernel" ([kernelconfig.html Chapter 9]) for more details on how to recompile your kernel.
14446 **Warning:** IPFW defaults to a policy of `deny ip from any to any`. If you do not add other rules during startup to allow access, ***you will lock yourself out*** of the server upon rebooting into a firewall-enabled kernel. We suggest that you set `firewall_type=open` in your `/etc/rc.conf` file when first enabling this feature, then refining the firewall rules in `/etc/rc.firewall` after you have tested that the new kernel feature works properly. To be on the safe side, you may wish to consider performing the initial firewall configuration from the local console rather than via **ssh** . Another option is to build a kernel using both the `IPFIREWALL` and `IPFIREWALL_DEFAULT_TO_ACCEPT` options. This will change the default rule of IPFW to `allow ip from any to any` and avoid the possibility of a lockout.
14448 There are currently four kernel configuration options relevant to IPFW:
14450 `options IPFIREWALL`:: Compiles into the kernel the code for packet filtering.`options IPFIREWALL_VERBOSE`:: Enables code to allow logging of packets through [syslogd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#syslogd§ion8). Without this option, even if you specify that packets should be logged in the filter rules, nothing will happen.`options IPFIREWALL_VERBOSE_LIMIT=10`:: Limits the number of packets logged through [syslogd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=syslogd§ion=8) on a per entry basis. You may wish to use this option in hostile environments in which you want to log firewall activity, but do not want to be open to a denial of service attack via syslog flooding.
14452 When a chain entry reaches the packet limit specified, logging is turned off for that particular entry. To resume logging, you will need to reset the associated counter using the [ipfw(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#ipfw§ion8) utility:
14458 Where 4500 is the chain entry you wish to continue logging.`options IPFIREWALL_DEFAULT_TO_ACCEPT`:: This changes the default rule action from ***deny*** to ***allow***. This avoids the possibility of locking yourself out if you happen to boot a kernel with `IPFIREWALL` support but have not configured your firewall yet. It is also very useful if you often use [ipfw(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#ipfw§ion8) as a filter for specific problems as they arise. Use with care though, as this opens up the firewall and changes the way it works.
14460 #### Configuring IPFW
14462 The configuration of the IPFW software is done through the [ipfw(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#ipfw§ion8) utility. The syntax for this command looks quite complicated, but it is relatively simple once you understand its structure.
14464 There are currently four different command categories used by the utility: addition/deletion, listing, flushing, and clearing. Addition/deletion is used to build the rules that control how packets are accepted, rejected, and logged. Listing is used to examine the contents of your rule set (otherwise known as the chain) and packet counters (accounting). Flushing is used to remove all entries from the chain. Clearing is used to zero out one or more accounting entries.
14466 ##### Altering the IPFW Rules
14468 The syntax for this form of the command is:
14470 `ipfw` [-N] command [index] action [log] protocol addresses [options]
14472 There is one valid flag when using this form of the command:
14474 -N:: Resolve addresses and service names in output.
14476 The ***command*** given can be shortened to the shortest unique form. The valid ***commands*** are:
14478 add:: Add an entry to the firewall/accounting rule listdelete:: Delete an entry from the firewall/accounting rule list
14480 Previous versions of IPFW used separate firewall and accounting entries. The present version provides packet accounting with each firewall entry.
14482 If an ***index*** value is supplied, it is used to place the entry at a specific point in the chain. Otherwise, the entry is placed at the end of the chain at an index 100 greater than the last chain entry (this does not include the default policy, rule 65535, deny).
14484 The `log` option causes matching rules to be output to the system console if the kernel was compiled with `IPFIREWALL_VERBOSE`.
14486 Valid ***actions*** are:
14488 reject:: Drop the packet, and send an ICMP host or port unreachable (as appropriate) packet to the source.allow:: Pass the packet on as normal. (aliases: `pass`, `permit`, and `accept`)deny:: Drop the packet. The source is not notified via an ICMP message (thus it appears that the packet never arrived at the destination).count:: Update packet counters but do not allow/deny the packet based on this rule. The search continues with the next chain entry.
14490 Each ***action*** will be recognized by the shortest unambiguous prefix.
14492 The ***protocols*** which can be specified are:
14494 all:: Matches any IP packeticmp:: Matches ICMP packetstcp:: Matches TCP packetsudp:: Matches UDP packets
14496 The ***address*** specification is:
14498 from `***address/mask***` [`***port***`] to `***address/mask***` [`***port***`] [via `***interface***`]
14500 You can only specify `***port***` in conjunction with ***protocols*** which support ports (UDP and TCP).
14502 The `via` is optional and may specify the IP address or domain name of a local IP interface, or an interface name (e.g. `ed0`) to match only packets coming through this interface. Interface unit numbers can be specified with an optional wildcard. For example, `ppp*` would match all kernel PPP interfaces.
14504 The syntax used to specify an `***address/mask***` is:
14514 `***address***`/`***mask-bits***`
14520 `***address***`:`***mask-pattern***`
14522 A valid hostname may be specified in place of the IP address. ' **mask-bits** ' is a decimal number representing how many bits in the address mask should be set. e.g. specifying `192.216.222.1/24` will create a mask which will allow any address in a class C subnet (in this case, `192.216.222`) to be matched. ' **mask-pattern** ' is an IP address which will be logically AND'ed with the address given. The keyword `any` may be used to specify ***any IP address***.
14524 The port numbers to be blocked are specified as:
14526 `***port***` [,`***port***` [,`***port***` [...]]]
14528 to specify either a single port or a list of ports, or
14530 `***port***`-`***port***`
14532 to specify a range of ports. You may also combine a single range with a list, but the range must always be specified first.
14534 The ***options*** available are:
14536 frag:: Matches if the packet is not the first fragment of the datagram.in:: Matches if the packet is on the way in.out:: Matches if the packet is on the way out.ipoptions `***spec***`:: Matches if the IP header contains the comma separated list of options specified in `***spec***`. The supported IP options are: `ssrr` (strict source route), `lsrr` (loose source route), `rr` (record packet route), and `ts` (time stamp). The absence of a particular option may be specified with a leading `!`.established:: Matches if the packet is part of an already established TCP connection (i.e. it has the RST or ACK bits set). You can optimize the performance of the firewall by placing ***established*** rules early in the chain.setup:: Matches if the packet is an attempt to establish a TCP connection (the SYN bit is set but the ACK bit is not).tcpflags `***flags***`:: Matches if the TCP header contains the comma separated list of `***flags***`. The supported flags are `fin`, `syn`, `rst`, `psh`, `ack`, and `urg`. The absence of a particular flag may be indicated by a leading `!`.icmptypes `***types***`:: Matches if the ICMP type is present in the list `***types***`. The list may be specified as any combination of ranges and/or individual types separated by commas. Commonly used ICMP types are: `0` echo reply (ping reply), `3` destination unreachable, `5` redirect, `8` echo request (ping request), and `11` time exceeded (used to indicate TTL expiration as with [traceroute(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#traceroute§ion8)).
14538 ##### Listing the IPFW Rules
14540 The syntax for this form of the command is:
14542 `ipfw` [-a] [-c] [-d] [-e] [-t] [-N] [-S] list
14544 There are seven valid flags when using this form of the command:
14546 -a:: While listing, show counter values. This option is the only way to see accounting counters.-c:: List rules in compact form.-d:: Show dynamic rules in addition to static rules.-e:: If `-d` was specified, also show expired dynamic rules.-t:: Display the last match times for each chain entry. The time listing is incompatible with the input syntax used by the [ipfw(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#ipfw§ion8) utility.-N:: Attempt to resolve given addresses and service names.-S:: Show the set each rule belongs to. If this flag is not specified, disabled rules will not be listed.
14548 ##### Flushing the IPFW Rules
14550 The syntax for flushing the chain is:
14554 This causes all entries in the firewall chain to be removed except the fixed default policy enforced by the kernel (index 65535). Use caution when flushing rules; the default deny policy will leave your system cut off from the network until allow entries are added to the chain.
14556 ##### Clearing the IPFW Packet Counters
14558 The syntax for clearing one or more packet counters is:
14560 `ipfw` zero [`***index***`]
14562 When used without an `***index***` argument, all packet counters are cleared. If an `***index***` is supplied, the clearing operation only affects a specific chain entry.
14564 #### Example Commands for **ipfw**
14566 This command will deny all packets from the host `evil.crackers.org` to the telnet port of the host `nice.people.org`:
14570 # ipfw add deny tcp from evil.crackers.org to nice.people.org 23
14572 The next example denies and logs any TCP traffic from the entire `crackers.org` network (a class C) to the `nice.people.org` machine (any port).
14576 # ipfw add deny log tcp from evil.crackers.org/24 to nice.people.org
14578 If you do not want people sending X sessions to your internal network (a subnet of a class C), the following command will do the necessary filtering:
14582 # ipfw add deny tcp from any to my.org/28 6000 setup
14584 To see the accounting records:
14590 or in the short form
14596 You can also see the last time a chain entry was matched with:
14602 #### Building a Packet Filtering Firewall
14604 **Note:** The following suggestions are just that: suggestions. The requirements of each firewall are different and we cannot tell you how to build a firewall to meet your particular requirements.
14606 When initially setting up your firewall, unless you have a test bench setup where you can configure your firewall host in a controlled environment, it is strongly recommend you use the logging version of the commands and enable logging in the kernel. This will allow you to quickly identify problem areas and cure them without too much disruption. Even after the initial setup phase is complete, I recommend using the logging for `deny' as it allows tracing of possible attacks and also modification of the firewall rules if your requirements alter.
14608 **Note:** If you use the logging versions of the `accept` command, be aware that it can generate ***large*** amounts of log data. One log entry will be generated for every packet that passes through the firewall, so large FTP/http transfers, etc, will really slow the system down. It also increases the latencies on those packets as it requires more work to be done by the kernel before the packet can be passed on. **syslogd** will also start using up a lot more processor time as it logs all the extra data to disk, and it could quite easily fill the partition `/var/log` is located on.
14610 You should enable your firewall from `/etc/rc.conf.local` or `/etc/rc.conf`. The associated manual page explains which knobs to fiddle and lists some preset firewall configurations. If you do not use a preset configuration, `ipfw list` will output the current ruleset into a file that you can pass to `rc.conf`. If you do not use `/etc/rc.conf.local` or `/etc/rc.conf` to enable your firewall, it is important to make sure your firewall is enabled before any IP interfaces are configured.
14612 The next problem is what your firewall should actually ***do***! This is largely dependent on what access to your network you want to allow from the outside, and how much access to the outside world you want to allow from the inside. Some general rules are:
14614 * Block all incoming access to ports below 1024 for TCP. This is where most of the security sensitive services are, like finger, SMTP (mail) and telnet.
14616 * Block ***all*** incoming UDP traffic. There are very few useful services that travel over UDP, and what useful traffic there is, is normally a security threat (e.g. Suns RPC and NFS protocols). This has its disadvantages also, since UDP is a connectionless protocol, denying incoming UDP traffic also blocks the replies to outgoing UDP traffic. This can cause a problem for people (on the inside) using external archie (prospero) servers. If you want to allow access to archie, you will have to allow packets coming from ports 191 and 1525 to any internal UDP port through the firewall. **ntp** is another service you may consider allowing through, which comes from port 123.
14618 * Block traffic to port 6000 from the outside. Port 6000 is the port used for access to X11 servers, and can be a security threat (especially if people are in the habit of doing `xhost +` on their workstations). X11 can actually use a range of ports starting at 6000, the upper limit being how many X displays you can run on the machine. The upper limit as defined by RFC 1700 (Assigned Numbers) is 6063.
14620 * Check what ports any internal servers use (e.g. SQL servers, etc). It is probably a good idea to block those as well, as they normally fall outside the 1-1024 range specified above.
14622 Another checklist for firewall configuration is available from CERT at http://www.cert.org/tech_tips/packet_filtering.html
14624 As stated above, these are only ***guidelines***. You will have to decide what filter rules you want to use on your firewall yourself. We cannot accept ANY responsibility if someone breaks into your network, even if you follow the advice given above.
14626 #### IPFW Overhead and Optimization
14628 Many people want to know how much overhead IPFW adds to a system. The answer to this depends mostly on your rule set and processor speed. For most applications dealing with Ethernet and small rule sets, the answer is ***negligible***. For those of you that need actual measurements to satisfy your curiosity, read on.
14630 The following measurements were made using FreeBSD 2.2.5-STABLE on a 486-66. (While IPFW has changed slightly in later releases of DragonFly, it still performs with similar speed.) IPFW was modified to measure the time spent within the `ip_fw_chk` routine, displaying the results to the console every 1000 packets.
14632 Two rule sets, each with 1000 rules, were tested. The first set was designed to demonstrate a worst case scenario by repeating the rule:
14636 # ipfw add deny tcp from any to any 55555
14638 This demonstrates a worst case scenario by causing most of IPFW's packet check routine to be executed before finally deciding that the packet does not match the rule (by virtue of the port number). Following the 999th iteration of this rule was an `allow ip from any to any`.
14640 The second set of rules were designed to abort the rule check quickly:
14644 # ipfw add deny ip from 1.2.3.4 to 1.2.3.4
14646 The non-matching source IP address for the above rule causes these rules to be skipped very quickly. As before, the 1000th rule was an `allow ip from any to any`.
14648 The per-packet processing overhead in the former case was approximately 2.703 ms/packet, or roughly 2.7 microseconds per rule. Thus the theoretical packet processing limit with these rules is around 370 packets per second. Assuming 10 Mbps Ethernet and a ~1500 byte packet size, we would only be able to achieve 55.5% bandwidth utilization.
14650 For the latter case each packet was processed in approximately 1.172 ms, or roughly 1.2 microseconds per rule. The theoretical packet processing limit here would be about 853 packets per second, which could consume 10 Mbps Ethernet bandwidth.
14652 The excessive number of rules tested and the nature of those rules do not provide a real-world scenario -- they were used only to generate the timing information presented here. Here are a few things to keep in mind when building an efficient rule set:
14654 * Place an `established` rule early on to handle the majority of TCP traffic. Do not put any `allow tcp` statements before this rule.
14656 * Place heavily triggered rules earlier in the rule set than those rarely used (***without changing the permissiveness of the firewall***, of course). You can see which rules are used most often by examining the packet counting statistics with `ipfw -a l`.
14660 CategoryHandbook-security
14664 [OpenSSL](http://www.openssl.org/) provides a general-purpose cryptography library, as well as the Secure Sockets Layer v2/v3 (SSLv2/SSLv3) and Transport Layer Security v1 (TLSv1) network security protocols.
14666 However, one of the algorithms (specifically IDEA) included in OpenSSL is protected by patents in the USA and elsewhere, and is not available for unrestricted use. IDEA is included in the OpenSSL sources in DragonFly, but it is not built by default. If you wish to use it, and you comply with the license terms, enable the `MAKE_IDEA` switch in `/etc/make.conf` and rebuild your sources using `make world`.
14668 Today, the RSA algorithm is free for use in USA and other countries. In the past it was protected by a patent.
14672 <!-- XXX: someone revise this and add words about pf. I've no clue about this stuff -->
14674 ***Written by Nik Clayton. ***
14676 Creating a VPN between two networks, separated by the Internet, using DragonFly gateways.
14678 ### Understanding IPsec
14680 ***Written by Hiten M. Pandya. ***
14682 This section will guide you through the process of setting up IPsec, and to use it in an environment which consists of DragonFly and **Microsoft® Windows® 2000/XP** machines, to make them communicate securely. In order to set up IPsec, it is necessary that you are familiar with the concepts of building a custom kernel (see [kernelconfig.html Chapter 9]).
14684 ***IPsec*** is a protocol which sits on top of the Internet Protocol (IP) layer. It allows two or more hosts to communicate in a secure manner (hence the name). The DragonFly IPsec ***network stack*** is based on the [KAME](http://www.kame.net/) implementation, which has support for both protocol families, IPv4 and IPv6.
14686 IPsec consists of two sub-protocols:
14688 * ***Encapsulated Security Payload (ESP)***, protects the IP packet data from third party interference, by encrypting the contents using symmetric cryptography algorithms (like Blowfish, 3DES).
14690 * ***Authentication Header (AH)***, protects the IP packet header from third party interference and spoofing, by computing a cryptographic checksum and hashing the IP packet header fields with a secure hashing function. This is then followed by an additional header that contains the hash, to allow the information in the packet to be authenticated.
14692 ESP and AH can either be used together or separately, depending on the environment.
14694 IPsec can either be used to directly encrypt the traffic between two hosts (known as ***Transport Mode***); or to build ***virtual tunnels*** between two subnets, which could be used for secure communication between two corporate networks (known as ***Tunnel Mode***). The latter is more commonly known as a ***Virtual Private Network (VPN)***. The [ipsec(4)](http://leaf.dragonflybsd.org/cgi/web-man?command#ipsec§ion4) manual page should be consulted for detailed information on the IPsec subsystem in DragonFly.
14696 To add IPsec support to your kernel, add the following options to your kernel configuration file:
14700 options IPSEC #IP security
14702 options IPSEC_ESP #IP security (crypto; define w/ IPSEC)
14706 If IPsec debugging support is desired, the following kernel option should also be added:
14710 options IPSEC_DEBUG #debug for IP security
14716 There's no standard for what constitutes a VPN. VPNs can be implemented using a number of different technologies, each of which have their own strengths and weaknesses. This article presents a number of scenarios, and strategies for implementing a VPN for each scenario.
14718 ### Scenario #1: Two networks, connected to the Internet, to behave as one
14720 This is the scenario that caused me to first investigating VPNs. The premise is as follows:
14722 * You have at least two sites
14724 * Both sites are using IP internally
14726 * Both sites are connected to the Internet, through a gateway that is running DragonFly.
14728 * The gateway on each network has at least one public IP address.
14730 * The internal addresses of the two networks can be public or private IP addresses, it doesn't matter. You can be running NAT on the gateway machine if necessary.
14732 * The internal IP addresses of the two networks ***do not collide***. While I expect it is theoretically possible to use a combination of VPN technology and NAT to get this to work, I expect it to be a configuration nightmare.
14734 If you find that you are trying to connect two networks, both of which, internally, use the same private IP address range (e.g., both of them use `192.168.1.x`), then one of the networks will have to be renumbered.
14736 The network topology might look something like this:
14738 security/ipsec-network.png
14740 Notice the two public IP addresses. I'll use the letters to refer to them in the rest of this article. Anywhere you see those letters in this article, replace them with your own public IP addresses. Note also that internally, the two gateway machines have .1 IP addresses, and that the two networks have different private IP addresses (`192.168.1.x` and `192.168.2.x` respectively). All the machines on the private networks have been configured to use the `.1` machine as their default gateway.
14742 The intention is that, from a network point of view, each network should view the machines on the other network as though they were directly attached the same router -- albeit a slightly slow router with an occasional tendency to drop packets.
14744 This means that (for example), machine `192.168.1.20` should be able to run
14750 and have it work, transparently. Windows machines should be able to see the machines on the other network, browse file shares, and so on, in exactly the same way that they can browse machines on the local network.
14752 And the whole thing has to be secure. This means that traffic between the two networks has to be encrypted.
14754 Creating a VPN between these two networks is a multi-step process. The stages are as follows:
14756 1. Create a ***virtual*** network link between the two networks, across the Internet. Test it, using tools like [ping(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#ping§ion8), to make sure it works.
14758 1. Apply security policies to ensure that traffic between the two networks is transparently encrypted and decrypted as necessary. Test this, using tools like [tcpdump(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#tcpdump§ion1), to ensure that traffic is encrypted.
14760 1. Configure additional software on the DragonFly gateways, to allow Windows machines to see one another across the VPN.
14762 #### Step 1: Creating and testing a ***virtual*** network link
14764 Suppose that you were logged in to the gateway machine on network #1 (with public IP address `A.B.C.D`, private IP address `192.168.1.1`), and you ran `ping 192.168.2.1`, which is the private address of the machine with IP address `W.X.Y.Z`. What needs to happen in order for this to work?
14766 1. The gateway machine needs to know how to reach `192.168.2.1`. In other words, it needs to have a route to `192.168.2.1`.
14768 1. Private IP addresses, such as those in the `192.168.x` range are not supposed to appear on the Internet at large. Instead, each packet you send to `192.168.2.1` will need to be wrapped up inside another packet. This packet will need to appear to be from `A.B.C.D`, and it will have to be sent to `W.X.Y.Z`. This process is called ***encapsulation***.
14770 1. Once this packet arrives at `W.X.Y.Z` it will need to ***unencapsulated***, and delivered to `192.168.2.1`.
14772 You can think of this as requiring a ***tunnel*** between the two networks. The two ***tunnel mouths*** are the IP addresses `A.B.C.D` and `W.X.Y.Z`, and the tunnel must be told the addresses of the private IP addresses that will be allowed to pass through it. The tunnel is used to transfer traffic with private IP addresses across the public Internet.
14774 This tunnel is created by using the generic interface, or `gif` devices on DragonFly. As you can imagine, the `gif` interface on each gateway host must be configured with four IP addresses; two for the public IP addresses, and two for the private IP addresses.
14776 Support for the gif device must be compiled in to the DragonFly kernel on both machines. You can do this by adding the line:
14782 to the kernel configuration files on both machines, and then compile, install, and reboot as normal.
14784 Configuring the tunnel is a two step process. First the tunnel must be told what the outside (or public) IP addresses are, using [gifconfig(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#gifconfig§ion8). Then the private IP addresses must be configured using [ifconfig(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=ifconfig§ion=8).
14786 On the gateway machine on network #1 you would run the following two commands to configure the tunnel.
14790 gifconfig gif0 A.B.C.D W.X.Y.Z
14792 ifconfig gif0 inet 192.168.1.1 192.168.2.1 netmask 0xffffffff
14796 On the other gateway machine you run the same commands, but with the order of the IP addresses reversed.
14800 gifconfig gif0 W.X.Y.Z A.B.C.D
14802 ifconfig gif0 inet 192.168.2.1 192.168.1.1 netmask 0xffffffff
14812 to see the configuration. For example, on the network #1 gateway, you would see this:
14818 gif0: flags=8011<UP,POINTTOPOINT,MULTICAST> mtu 1280
14820 inet 192.168.1.1 --> 192.168.2.1 netmask 0xffffffff
14822 physical address inet A.B.C.D --> W.X.Y.Z
14826 As you can see, a tunnel has been created between the physical addresses `A.B.C.D` and `W.X.Y.Z`, and the traffic allowed through the tunnel is that between `192.168.1.1` and `192.168.2.1`.
14828 This will also have added an entry to the routing table on both machines, which you can examine with the command `netstat -rn`. This output is from the gateway host on network #1.
14840 Destination Gateway Flags Refs Use Netif Expire
14844 192.168.2.1 192.168.1.1 UH 0 0 gif0
14850 As the ***Flags*** value indicates, this is a host route, which means that each gateway knows how to reach the other gateway, but they do not know how to reach the rest of their respective networks. That problem will be fixed shortly.
14852 It is likely that you are running a firewall on both machines. This will need to be circumvented for your VPN traffic. You might want to allow all traffic between both networks, or you might want to include firewall rules that protect both ends of the VPN from one another.
14854 It greatly simplifies testing if you configure the firewall to allow all traffic through the VPN. You can always tighten things up later. If you are using [ipfw(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#ipfw§ion8) on the gateway machines then a command like
14858 ipfw add 1 allow ip from any to any via gif0
14860 will allow all traffic between the two end points of the VPN, without affecting your other firewall rules. Obviously you will need to run this command on both gateway hosts.
14862 This is sufficient to allow each gateway machine to ping the other. On `192.168.1.1`, you should be able to run
14868 and get a response, and you should be able to do the same thing on the other gateway machine.
14870 However, you will not be able to reach internal machines on either network yet. This is because of the routing -- although the gateway machines know how to reach one another, they do not know how to reach the network behind each one.
14872 To solve this problem you must add a static route on each gateway machine. The command to do this on the first gateway would be:
14876 route add 192.168.2.0 192.168.2.1 netmask 0xffffff00
14880 This says ***In order to reach the hosts on the network `192.168.2.0`, send the packets to the host `192.168.2.1`***. You will need to run a similar command on the other gateway, but with the `192.168.1.x` addresses instead.
14882 IP traffic from hosts on one network will now be able to reach hosts on the other network.
14884 That has now created two thirds of a VPN between the two networks, in as much as it is ***virtual*** and it is a ***network***. It is not private yet. You can test this using [ping(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#ping§ion8) and [tcpdump(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=tcpdump§ion=1). Log in to the gateway host and run
14888 tcpdump dst host 192.168.2.1
14890 In another log in session on the same host run
14896 You will see output that looks something like this:
14900 16:10:24.018080 192.168.1.1 > 192.168.2.1: icmp: echo request
14902 16:10:24.018109 192.168.1.1 > 192.168.2.1: icmp: echo reply
14904 16:10:25.018814 192.168.1.1 > 192.168.2.1: icmp: echo request
14906 16:10:25.018847 192.168.1.1 > 192.168.2.1: icmp: echo reply
14908 16:10:26.028896 192.168.1.1 > 192.168.2.1: icmp: echo request
14910 16:10:26.029112 192.168.1.1 > 192.168.2.1: icmp: echo reply
14914 As you can see, the ICMP messages are going back and forth unencrypted. If you had used the `-s` parameter to [tcpdump(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#tcpdump§ion1) to grab more bytes of data from the packets you would see more information.
14916 Obviously this is unacceptable. The next section will discuss securing the link between the two networks so that it all traffic is automatically encrypted.
14920 * Configure both kernels with ***pseudo-device gif***.
14922 * Edit `/etc/rc.conf` on gateway host #1 and add the following lines (replacing IP addresses as necessary).
14926 gifconfig_gif0="A.B.C.D W.X.Y.Z"
14928 ifconfig_gif0="inet 192.168.1.1 192.168.2.1 netmask 0xffffffff"
14930 static_routes="vpn"
14932 route_vpn="192.168.2.0 192.168.2.1 netmask 0xffffff00"
14936 * Edit your firewall script (`/etc/rc.firewall`, or similar) on both hosts, and add
14940 ipfw add 1 allow ip from any to any via gif0
14944 * Make similar changes to `/etc/rc.conf` on gateway host #2, reversing the order of IP addresses.
14946 #### Step 2: Securing the link
14948 To secure the link we will be using IPsec. IPsec provides a mechanism for two hosts to agree on an encryption key, and to then use this key in order to encrypt data between the two hosts.
14950 The are two areas of configuration to be considered here.
14952 1. There must be a mechanism for two hosts to agree on the encryption mechanism to use. Once two hosts have agreed on this mechanism there is said to be a ***security association*** between them.
14954 1. There must be a mechanism for specifying which traffic should be encrypted. Obviously, you don't want to encrypt all your outgoing traffic -- you only want to encrypt the traffic that is part of the VPN. The rules that you put in place to determine what traffic will be encrypted are called ***security policies***.
14956 Security associations and security policies are both maintained by the kernel, and can be modified by userland programs. However, before you can do this you must configure the kernel to support IPsec and the Encapsulated Security Payload (ESP) protocol. This is done by configuring a kernel with:
14966 and recompiling, reinstalling, and rebooting. As before you will need to do this to the kernels on both of the gateway hosts.
14968 You have two choices when it comes to setting up security associations. You can configure them by hand between two hosts, which entails choosing the encryption algorithm, encryption keys, and so forth, or you can use daemons that implement the Internet Key Exchange protocol (IKE) to do this for you.
14970 I recommend the latter. Apart from anything else, it is easier to set up.
14972 Editing and displaying security policies is carried out using [setkey(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#setkey§ion8). By analogy, `setkey` is to the kernel's security policy tables as [route(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=route§ion=8) is to the kernel's routing tables. `setkey` can also display the current security associations, and to continue the analogy further, is akin to `netstat -r` in that respect.
14974 There are a number of choices for daemons to manage security associations with DragonFly. This article will describe how to use one of these, racoon. racoon is in the FreeBSD ports collection, in the security/ category, and is installed in the usual way.
14976 racoon must be run on both gateway hosts. On each host it is configured with the IP address of the other end of the VPN, and a secret key (which you choose, and must be the same on both gateways).
14978 The two daemons then contact one another, confirm that they are who they say they are (by using the secret key that you configured). The daemons then generate a new secret key, and use this to encrypt the traffic over the VPN. They periodically change this secret, so that even if an attacker were to crack one of the keys (which is as theoretically close to unfeasible as it gets) it won't do them much good -- by the time they've cracked the key the two daemons have chosen another one.
14980 racoon's configuration is stored in `${PREFIX}/etc/racoon`. You should find a configuration file there, which should not need to be changed too much. The other component of racoon's configuration, which you will need to change, is the ***pre-shared key***.
14982 The default racoon configuration expects to find this in the file `${PREFIX}/etc/racoon/psk.txt`. It is important to note that the pre-shared key is ***not*** the key that will be used to encrypt your traffic across the VPN link, it is simply a token that allows the key management daemons to trust one another.
14984 `psk.txt` contains a line for each remote site you are dealing with. In this example, where there are two sites, each `psk.txt` file will contain one line (because each end of the VPN is only dealing with one other end).
14986 On gateway host #1 this line should look like this:
14992 That is, the ***public*** IP address of the remote end, whitespace, and a text string that provides the secret. Obviously, you shouldn't use ***secret*** as your key -- the normal rules for choosing a password apply.
14994 On gateway host #2 the line would look like this
15000 That is, the public IP address of the remote end, and the same secret key. `psk.txt` must be mode `0600` (i.e., only read/write to `root`) before racoon will run.
15002 You must run racoon on both gateway machines. You will also need to add some firewall rules to allow the IKE traffic, which is carried over UDP to the ISAKMP (Internet Security Association Key Management Protocol) port. Again, this should be fairly early in your firewall ruleset.
15006 ipfw add 1 allow udp from A.B.C.D to W.X.Y.Z isakmp
15008 ipfw add 1 allow udp from W.X.Y.Z to A.B.C.D isakmp
15012 Once racoon is running you can try pinging one gateway host from the other. The connection is still not encrypted, but racoon will then set up the security associations between the two hosts -- this might take a moment, and you may see this as a short delay before the ping commands start responding.
15014 Once the security association has been set up you can view it using [setkey(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#setkey§ion8). Run
15020 on either host to view the security association information.
15022 That's one half of the problem. They other half is setting your security policies.
15024 To create a sensible security policy, let's review what's been set up so far. This discussions hold for both ends of the link.
15026 Each IP packet that you send out has a header that contains data about the packet. The header includes the IP addresses of both the source and destination. As we already know, private IP addresses, such as the `192.168.x.y` range are not supposed to appear on the public Internet. Instead, they must first be encapsulated inside another packet. This packet must have the public source and destination IP addresses substituted for the private addresses.
15028 So if your outgoing packet started looking like this:
15030 security/ipsec-out-pkt.png
15032 Then it will be encapsulated inside another packet, looking something like this:
15034 security/ipsec-encap-pkt.png
15036 This encapsulation is carried out by the `gif` device. As you can see, the packet now has real IP addresses on the outside, and our original packet has been wrapped up as data inside the packet that will be put out on the Internet.
15038 Obviously, we want all traffic between the VPNs to be encrypted. You might try putting this in to words, as:
15040 ***If a packet leaves from `A.B.C.D`, and it is destined for `W.X.Y.Z`, then encrypt it, using the necessary security associations.***
15042 ***If a packet arrives from `W.X.Y.Z`, and it is destined for `A.B.C.D`, then decrypt it, using the necessary security associations.***
15044 That's close, but not quite right. If you did this, all traffic to and from `W.X.Y.Z`, even traffic that was not part of the VPN, would be encrypted. That's not quite what you want. The correct policy is as follows
15046 ***If a packet leaves from `A.B.C.D`, and that packet is encapsulating another packet, and it is destined for `W.X.Y.Z`, then encrypt it, using the necessary security associations.***
15048 ***If a packet arrives from `W.X.Y.Z`, and that packet is encapsulating another packet, and it is destined for `A.B.C.D`, then encrypt it, using the necessary security associations.***
15050 A subtle change, but a necessary one.
15052 Security policies are also set using [setkey(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#setkey§ion8). [setkey(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=setkey§ion=8) features a configuration language for defining the policy. You can either enter configuration instructions via stdin, or you can use the `-f` option to specify a filename that contains configuration instructions.
15054 The configuration on gateway host #1 (which has the public IP address `A.B.C.D`) to force all outbound traffic to `W.X.Y.Z` to be encrypted is:
15058 spdadd A.B.C.D/32 W.X.Y.Z/32 ipencap -P out ipsec esp/tunnel/A.B.C.D-W.X.Y.Z/require;
15062 Put these commands in a file (e.g., `/etc/ipsec.conf`) and then run
15066 # setkey -f /etc/ipsec.conf
15068 `spdadd` tells [setkey(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#setkey§ion8) that we want to add a rule to the secure policy database. The rest of this line specifies which packets will match this policy. `A.B.C.D/32` and `W.X.Y.Z/32` are the IP addresses and netmasks that identify the network or hosts that this policy will apply to. In this case, we want it to apply to traffic between these two hosts. `ipencap` tells the kernel that this policy should only apply to packets that encapsulate other packets. `-P out` says that this policy applies to outgoing packets, and `ipsec` says that the packet will be secured.
15070 The second line specifies how this packet will be encrypted. `esp` is the protocol that will be used, while `tunnel` indicates that the packet will be further encapsulated in an IPsec packet. The repeated use of `A.B.C.D` and `W.X.Y.Z` is used to select the security association to use, and the final `require` mandates that packets must be encrypted if they match this rule.
15072 This rule only matches outgoing packets. You will need a similar rule to match incoming packets.
15076 spdadd W.X.Y.Z/32 A.B.C.D/32 ipencap -P in ipsec esp/tunnel/W.X.Y.Z-A.B.C.D/require;
15078 Note the `in` instead of `out` in this case, and the necessary reversal of the IP addresses.
15080 The other gateway host (which has the public IP address `W.X.Y.Z`) will need similar rules.
15084 spdadd W.X.Y.Z/32 A.B.C.D/32 ipencap -P out ipsec esp/tunnel/W.X.Y.Z-A.B.C.D/require;
15086 spdadd A.B.C.D/32 W.X.Y.Z/32 ipencap -P in ipsec esp/tunnel/A.B.C.D-W.X.Y.Z/require;
15088 Finally, you need to add firewall rules to allow ESP and IPENCAP packets back and forth. These rules will need to be added to both hosts.
15092 ipfw add 1 allow esp from A.B.C.D to W.X.Y.Z
15094 ipfw add 1 allow esp from W.X.Y.Z to A.B.C.D
15096 ipfw add 1 allow ipencap from A.B.C.D to W.X.Y.Z
15098 ipfw add 1 allow ipencap from W.X.Y.Z to A.B.C.D
15102 Because the rules are symmetric you can use the same rules on each gateway host.
15104 Outgoing packets will now look something like this:
15106 security/ipsec-crypt-pkt.png
15108 When they are received by the far end of the VPN they will first be decrypted (using the security associations that have been negotiated by racoon). Then they will enter the `gif` interface, which will unwrap the second layer, until you are left with the innermost packet, which can then travel in to the inner network.
15110 You can check the security using the same [ping(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#ping§ion8) test from earlier. First, log in to the `A.B.C.D` gateway machine, and run:
15114 tcpdump dst host 192.168.2.1
15116 In another log in session on the same host run
15122 This time you should see output like the following:
15128 Now, as you can see, [tcpdump(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#tcpdump§ion1) shows the ESP packets. If you try to examine them with the `-s` option you will see (apparently) gibberish, because of the encryption.
15130 Congratulations. You have just set up a VPN between two remote sites.
15134 * Configure both kernels with:
15144 * Install [`security/racoon`](http://pkgsrc.se/security/racoon). Edit `${PREFIX}/etc/racoon/psk.txt` on both gateway hosts, adding an entry for the remote host's IP address and a secret key that they both know. Make sure this file is mode 0600.
15146 * Add the following lines to `/etc/rc.conf` on each host:
15152 ipsec_file="/etc/ipsec.conf"
15156 * Create an `/etc/ipsec.conf` on each host that contains the necessary spdadd lines. On gateway host #1 this would be:
15160 spdadd A.B.C.D/32 W.X.Y.Z/32 ipencap -P out ipsec
15162 esp/tunnel/A.B.C.D-W.X.Y.Z/require;
15164 spdadd W.X.Y.Z/32 A.B.C.D/32 ipencap -P in ipsec
15166 esp/tunnel/W.X.Y.Z-A.B.C.D/require;
15170 On gateway host #2 this would be:
15174 spdadd W.X.Y.Z/32 A.B.C.D/32 ipencap -P out ipsec
15176 esp/tunnel/W.X.Y.Z-A.B.C.D/require;
15178 spdadd A.B.C.D/32 W.X.Y.Z/32 ipencap -P in ipsec
15180 esp/tunnel/A.B.C.D-W.X.Y.Z/require;
15184 * Add firewall rules to allow IKE, ESP, and IPENCAP traffic to both hosts:
15188 ipfw add 1 allow udp from A.B.C.D to W.X.Y.Z isakmp
15190 ipfw add 1 allow udp from W.X.Y.Z to A.B.C.D isakmp
15192 ipfw add 1 allow esp from A.B.C.D to W.X.Y.Z
15194 ipfw add 1 allow esp from W.X.Y.Z to A.B.C.D
15196 ipfw add 1 allow ipencap from A.B.C.D to W.X.Y.Z
15198 ipfw add 1 allow ipencap from W.X.Y.Z to A.B.C.D
15202 The previous two steps should suffice to get the VPN up and running. Machines on each network will be able to refer to one another using IP addresses, and all traffic across the link will be automatically and securely encrypted.
15208 ***Contributed by Chern Lee. ***
15210 **OpenSSH** is a set of network connectivity tools used to access remote machines securely. It can be used as a direct replacement for `rlogin`, `rsh`, `rcp`, and `telnet`. Additionally, any other TCP/IP connections can be tunneled/forwarded securely through SSH. **OpenSSH** encrypts all traffic to effectively eliminate eavesdropping, connection hijacking, and other network-level attacks.
15212 **OpenSSH** is maintained by the OpenBSD project, and is based upon SSH v1.2.12 with all the recent bug fixes and updates. It is compatible with both SSH protocols 1 and 2.
15214 ### Advantages of Using OpenSSH
15216 Normally, when using [telnet(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#telnet§ion1) or [rlogin(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=rlogin§ion=1), data is sent over the network in an clear, un-encrypted form. Network sniffers anywhere in between the client and server can steal your user/password information or data transferred in your session. **OpenSSH** offers a variety of authentication and encryption methods to prevent this from happening.
15220 Be sure to make the following addition to your `rc.conf` file:
15226 This will load [sshd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#sshd§ion8&manpath=OpenBSD+3.3), the daemon program for **OpenSSH** , the next time your system initializes. Alternatively, you can simply run directly the **sshd** daemon by typing `rcstart sshd` on the command line.
15230 The [ssh(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ssh§ion1&manpath=OpenBSD+3.3) utility works similarly to [rlogin(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=rlogin§ion=1).
15234 # ssh user@example.com
15236 Host key not found from the list of known hosts.
15238 Are you sure you want to continue connecting (yes/no)? yes
15240 Host 'example.com' added to the list of known hosts.
15242 user@example.com's password: *******
15244 The login will continue just as it would have if a session was created using `rlogin` or `telnet`. SSH utilizes a key fingerprint system for verifying the authenticity of the server when the client connects. The user is prompted to enter `yes` only when connecting for the first time. Future attempts to login are all verified against the saved fingerprint key. The SSH client will alert you if the saved fingerprint differs from the received fingerprint on future login attempts. The fingerprints are saved in `~/.ssh/known_hosts`, or `~/.ssh/known_hosts2` for SSH v2 fingerprints.
15246 By default, **OpenSSH** servers are configured to accept both SSH v1 and SSH v2 connections. The client, however, can choose between the two. Version 2 is known to be more robust and secure than its predecessor.
15248 The [ssh(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ssh§ion1&manpath=OpenBSD+3.3) command can be forced to use either protocol by passing it the `-1` or `-2` argument for v1 and v2, respectively.
15252 The [scp(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#scp§ion1&manpath=OpenBSD+3.3) command works similarly to [rcp(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=rcp§ion=1); it copies a file to or from a remote machine, except in a secure fashion.
15256 # scp user@example.com:/COPYRIGHT COPYRIGHT
15258 user@example.com's password: *******
15260 COPYRIGHT 100% |*****************************| 4735
15266 Since the fingerprint was already saved for this host in the previous example, it is verified when using [scp(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#scp§ion1&manpath=OpenBSD+3.3) here.
15268 The arguments passed to [scp(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#scp§ion1&manpath=OpenBSD+3.3) are similar to [cp(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=cp§ion=1), with the file or files in the first argument, and the destination in the second. Since the file is fetched over the network, through SSH, one or more of the file arguments takes on the form `user@host:<path_to_remote_file>`. The `user@` part is optional. If omitted, it will default to the same username as you are currently logged in as, unless configured otherwise.
15272 The system-wide configuration files for both the **OpenSSH** daemon and client reside within the `/etc/ssh` directory.
15274 `ssh_config` configures the client settings, while `sshd_config` configures the daemon.
15276 Additionally, the `sshd_program` (`/usr/sbin/sshd` by default), and `sshd_flags` `rc.conf` options can provide more levels of configuration.
15278 Each user can have a personal configuration file in `~/.ssh/config`. The file can configure various client options, and can include host-specific options. With the following configuration file, a user could type `ssh shell` which would be equivalent to `ssh -X user@shell.example.com`.
15284 Hostname shell.example.com
15294 Instead of using passwords, [ssh-keygen(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ssh-keygen§ion1&manpath=OpenBSD+3.3) can be used to generate RSA keys to authenticate a user:
15298 % ssh-keygen -t rsa1
15300 Initializing random number generator...
15302 Generating p: .++ (distance 66)
15304 Generating q: ..............................++ (distance 498)
15306 Computing the keys...
15308 Key generation complete.
15310 Enter file in which to save the key (/home/user/.ssh/identity):
15314 Enter the same passphrase again:
15316 Your identification has been saved in /home/user/.ssh/identity.
15320 [ssh-keygen(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ssh-keygen§ion1&manpath=OpenBSD+3.3) will create a public and private key pair for use in authentication. The private key is stored in `~/.ssh/identity`, whereas the public key is stored in `~/.ssh/identity.pub`. The public key must be placed in `~/.ssh/authorized_keys` of the remote machine in order for the setup to work.
15322 This will allow connection to the remote machine based upon RSA authentication instead of passwords.
15324 **Note:** The `-t rsa1` option will create RSA keys for use by SSH protocol version 1. If you want to use RSA keys with the SSH protocol version 2, you have to use the command `ssh-keygen -t rsa`.
15326 If a passphrase is used in [ssh-keygen(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ssh-keygen§ion1&manpath=OpenBSD+3.3), the user will be prompted for a password each time in order to use the private key.
15328 A SSH protocol version 2 DSA key can be created for the same purpose by using the `ssh-keygen -t dsa` command. This will create a public/private DSA key for use in SSH protocol version 2 sessions only. The public key is stored in `~/.ssh/id_dsa.pub`, while the private key is in `~/.ssh/id_dsa`.
15330 DSA public keys are also placed in `~/.ssh/authorized_keys` on the remote machine.
15332 [ssh-agent(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ssh-agent§ion1&manpath=OpenBSD+3.3) and [ssh-add(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ssh-add§ion=1&manpath=OpenBSD+3.3) are utilities used in managing multiple passworded private keys.
15334 **Warning:** The various options and files can be different according to the **OpenSSH** version you have on your system, to avoid problems you should consult the [ssh-keygen(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ssh-keygen§ion1&manpath=OpenBSD+3.3) manual page.
15338 **OpenSSH** has the ability to create a tunnel to encapsulate another protocol in an encrypted session.
15340 The following command tells [ssh(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ssh§ion1&manpath=OpenBSD+3.3) to create a tunnel for **telnet** :
15344 % ssh -2 -N -f -L 5023:localhost:23 user@foo.example.com
15348 The `ssh` command is used with the following options:
15352 :: Forces `ssh` to use version 2 of the protocol. (Do not use if you are working with older SSH servers)
15356 :: Indicates no command, or tunnel only. If omitted, `ssh` would initiate a normal session.
15360 :: Forces `ssh` to run in the background.
15364 :: Indicates a local tunnel in `***localport:remotehost:remoteport***` fashion.
15366 `user@foo.example.com`
15368 :: The remote SSH server.
15370 An SSH tunnel works by creating a listen socket on `localhost` on the specified port. It then forwards any connection received on the local host/port via the SSH connection to the specified remote host and port.
15372 In the example, port `***5023***` on `localhost` is being forwarded to port `***23***` on `localhost` of the remote machine. Since `***23***` is **telnet** , this would create a secure **telnet** session through an SSH tunnel.
15374 This can be used to wrap any number of insecure TCP protocols such as SMTP, POP3, FTP, etc.
15376 **Example 10-1. Using SSH to Create a Secure Tunnel for SMTP**
15380 % ssh -2 -N -f -L 5025:localhost:25 user@mailserver.example.com
15382 user@mailserver.example.com's password: *****
15384 % telnet localhost 5025
15386 Trying 127.0.0.1...
15388 Connected to localhost.
15390 Escape character is '^]'.
15392 220 mailserver.example.com ESMTP
15394 This can be used in conjunction with an [ssh-keygen(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ssh-keygen§ion1&manpath=OpenBSD+3.3) and additional user accounts to create a more seamless/hassle-free SSH tunneling environment. Keys can be used in place of typing a password, and the tunnels can be run as a separate user.
15396 #### Practical SSH Tunneling Examples
15398 ##### Secure Access of a POP3 Server
15400 At work, there is an SSH server that accepts connections from the outside. On the same office network resides a mail server running a POP3 server. The network, or network path between your home and office may or may not be completely trustable. Because of this, you need to check your e-mail in a secure manner. The solution is to create an SSH connection to your office's SSH server, and tunnel through to the mail server.
15404 % ssh -2 -N -f -L 2110:mail.example.com:110 user@ssh-server.example.com
15406 user@ssh-server.example.com's password: ******
15408 When the tunnel is up and running, you can point your mail client to send POP3 requests to `localhost` port 2110. A connection here will be forwarded securely across the tunnel to `mail.example.com`.
15410 ##### Bypassing a Draconian Firewall
15412 Some network administrators impose extremely draconian firewall rules, filtering not only incoming connections, but outgoing connections. You may be only given access to contact remote machines on ports 22 and 80 for SSH and web surfing.
15414 You may wish to access another (perhaps non-work related) service, such as an Ogg Vorbis server to stream music. If this Ogg Vorbis server is streaming on some other port than 22 or 80, you will not be able to access it.
15416 The solution is to create an SSH connection to a machine outside of your network's firewall, and use it to tunnel to the Ogg Vorbis server.
15420 % ssh -2 -N -f -L 8888:music.example.com:8000 user@unfirewalled-system.example.org
15422 user@unfirewalled-system.example.org's password: *******
15424 Your streaming client can now be pointed to `localhost` port 8888, which will be forwarded over to `music.example.com` port 8000, successfully evading the firewall.
15426 ***Contributed by Matteo Riondato. Updated for DragonFly by Dario Banno.***
15432 This chapter will provide an explanation of what DragonFly jails are and how to use them. Jails, sometimes referred to as an enhanced replacement of chroot environments, are a very powerful tool for system administrators, but their basic usage can also be useful for advanced users.
15434 After reading this chapter, you will know:
15436 * What a jail is, and what purpose it may serve in DragonFly installations.
15438 * How to build, start, and stop a jail.
15440 * The basics of jail administration, both from inside and outside the jail.
15443 Other sources of useful information about jails are:
15445 * The [jail(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=jail§ion=8) manual page. This is the full reference of the jail utility -- the administrative tool which can be used in DragonFly to start, stop, and control DragonFly jails.
15447 * The mailing lists and their archives. The archives of the DragonFly general questions mailing list and other mailing lists hosted by the DragonFly list server already contain a wealth of material for jails. It should always be engaging to search the archives, or post a new question to the [users mailing list](mailto:users@lists.dragonflybsd.org).
15451 For information on how to setup a jail, see: [Setting up a jail](http://www.youtube.com/watch?v=s4_dJjfwtR4)
15455 ## Terms Related to Jails
15457 To facilitate better understanding of parts of the DragonFly system related to jails, their internals and the way they interact with the rest of DragonFly, the following terms are used further in this chapter:
15459 ***[chroot(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=chroot§ion=8) (command)***
15461 A system call of DragonFly, which changes the root directory of a process and all its descendants.
15465 ***[chroot(2)](http://leaf.dragonflybsd.org/cgi/web-man?command=chroot§ion=2) (environment)***
15467 The environment of processes running in a “chroot”. This includes resources such as the part of the file system which is visible, user and group IDs which are available, network interfaces and other IPC mechanisms, etc.
15471 *** [jail(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=jail§ion=8) (command)***
15473 The system administration utility which allows launching of processes within a jail environment.
15477 ***host (system, process, user, etc.)***
15479 The controlling system of a jail environment. The host system has access to all the hardware resources available, and can control processes both outside of and inside a jail environment. One of the important differences of the host system from a jail is that the limitations which apply to superuser processes inside a jail are not enforced for processes of the host system.
15483 ***hosted (system, process, user, etc.)***
15485 A process, user or other entity, whose access to resources is restricted by a DragonFly jail.
15491 Since system administration is a difficult and perplexing task, many powerful tools were developed to make life easier for the administrator. These tools mostly provide enhancements of some sort to the way systems are installed, configured and maintained. Part of the tasks which an administrator is expected to do is to properly configure the security of a system, so that it can continue serving its real purpose, without allowing security violations.
15494 One of the tools which can be used to enhance the security of a DragonFly system are jails. The jail feature was written by Poul-Henning Kamp <phk@freebsd.org> for R&D Associates [[http://www.rndassociates.com/]] who contributed it to FreeBSD 4.X. Support for multiple IPs and IPv6 were introduced in DragonFly 1.7. Their development still goes on, enhancing their usefulness, performance, reliability, and security.
15498 BSD-like operating systems have had [chroot(2)](http://leaf.dragonflybsd.org/cgi/web-man?command=chroot§ion=2) since the time of 4.2BSD. The [chroot(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=chroot§ion=8) utility can be used to change the root directory of a set of processes, creating a safe environment, separate from the rest of the system. Processes created in the chrooted environment can not access files or resources outside of it. For that reason, compromising a service running in a chrooted environment should not allow the attacker to compromise the entire system. The chroot(8) utility is good for easy tasks, which do not require a lot of flexibility or complex and advanced features. Since the inception of the chroot concept, however, many ways have been found to escape from a chrooted environment and, although they have been fixed in modern versions of the DragonFly kernel, it was clear that chroot(2) was not the ideal solution for securing services. A new subsystem had to be implemented.
15500 This is one of the main reasons why ***jails*** were developed.
15502 Jails improve on the concept of the traditional [chroot(2)](http://leaf.dragonflybsd.org/cgi/web-man?command=chroot§ion=2) environment, in several ways. In a traditional [chroot(2)](http://leaf.dragonflybsd.org/cgi/web-man?command=chroot§ion=2) environment, processes are only limited in the part of the file system they can access. The rest of the system resources (like the set of system users, the running processes, or the networking subsystem) are shared by the chrooted processes and the processes of the host system. Jails expand this model by virtualizing not only access to the file system, but also the set of users, the networking subsystem of the DragonFly kernel and a few other things. A more complete set of fine-grained controls available for tuning the access of a jailed environment is described in Section 12.5.
15505 A jail is characterized by four elements:
15507 * A directory subtree -- the starting point from which a jail is entered. Once inside the jail, a process is not permitted to escape outside of this subtree. Traditional security issues which plagued the original chroot(2) design will not affect DragonFly jails.
15509 * A hostname -- the hostname which will be used within the jail. Jails are mainly used for hosting network services, therefore having a descriptive hostname for each jail can really help the system administrator.
15511 * An IP address -- this will be assigned to the jail and cannot be changed in any way during the jail's life span. The IP address of a jail is usually an alias address for an existing network interface, but this is not strictly necessary.
15513 * A command -- the path name of an executable to run inside the jail. This is relative to the root directory of the jail environment, and may vary a lot, depending on the type of the specific jail environment.
15516 Apart from these, jails can have their own set of users and their own root user. Naturally, the powers of the root user are limited within the jail environment and, from the point of view of the host system, the jail root user is not an omnipotent user. In addition, the root user of a jail is not allowed to perform critical operations to the system outside of the associated jail(8) environment. More information about capabilities and restrictions of the root user will be discussed in Section 12.5 below.
15520 ## Creating and Controlling Jails
15522 Some administrators divide jails into the following two types: ***complete*** jails, which resemble a real DragonFly system, and ***service*** jails, dedicated to one application or service, possibly running with privileges. This is only a conceptual division and the process of building a jail is not affected by it. The [jail(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=jail§ion=8) manual page is quite clear about the procedure for building a jail:
15526 # setenv D /here/is/the/jail
15529 # make installworld DESTDIR=$D (2)
15531 # make distribution DESTDIR=$D -DNO_MAKEDEV_RUN (3)
15533 # ln -sf dev/null kernel
15534 # mount_devfs -o jail $D/dev
15539 Selecting a location for a jail is the best starting point. This is where the jail will physically reside within the file system of the jail's host. A good choice can be ***/usr/jail/jailname***, where jailname is the hostname identifying the jail. The ***/usr/*** file system usually has enough space for the jail file system, which for ***complete*** jails is, essentially, a replication of every file present in a default installation of the DragonFly base system.
15544 This command will populate the directory subtree chosen as jail's physical location on the file system with the necessary binaries, libraries, manual pages and so on. Everything is done in the typical DragonFly style -- first everything is built/compiled, then installed to the destination path.
15549 The distribution target for make installs every needed configuration file. In simple words, it installs every installable file of ***/usr/src/etc/*** to the ***/etc*** directory of the jail environment: ***$D/etc/***.
15553 Once a jail is installed, it can be started by using the [jail(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=jail§ion=8) utility. The [jail(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=jail§ion=8) utility takes four mandatory arguments which are described in the Section 12.3.1. Other arguments may be specified too, e.g., to run the jailed process with the credentials of a specific user. The command argument depends on the type of the jail; for a virtual system, ***/etc/rc*** is a good choice, since it will replicate the startup sequence of a real DragonFly system. For a service jail, it depends on the service or application that will run within the jail.
15555 Jails are often started at boot time and the DragonFly rc mechanism provides an easy way to do this.
15558 A list of the jails which are enabled to start at boot time should be added to the [rc.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=rc.conf§ion=5) file:
15562 jail_enable="YES" # Set to NO to disable starting of any jails
15563 jail_list="www" # Space separated list of names of jails
15568 For each jail listed in ***jail_list***, a group of [rc.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=rc.conf§ion=5) settings, which describe the particular jail, should be added:
15572 jail_www_rootdir="/usr/jail/www" # jail's root directory
15573 jail_www_hostname="www.example.org" # jail's hostname
15574 jail_www_ip="192.168.0.10" # jail's IP address
15577 The default startup of jails configured in [rc.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=rc.conf§ion=5), will run the ***/etc/rc*** script of the jail, which assumes the jail is a complete virtual system. For service jails, the default startup command of the jail should be changed, by setting the ***jail_jailname_exec_start*** option appropriately.
15579 **Note:** For a full list of available options, please see the [rc.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=rc.conf§ion=5) manual page.
15581 The ***/etc/rc.d/jail*** script can be used to start or stop a jail by hand, if an entry for it exists in ***rc.conf***:
15583 # /etc/rc.d/jail start www
15584 # /etc/rc.d/jail stop www
15588 A clean way to shut down a [jail(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=jail§ion=8) is not available at the moment. This is because commands normally used to accomplish a clean system shutdown cannot be used inside a jail. The best way to shut down a jail is to run the following command from within the jail itself or using the [jexec(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=jexec§ion=8) utility from outside the jail:
15592 # sh /etc/rc.shutdown
15594 More information about this can be found in the [jail(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=jail§ion=8) manual page.
15598 ## Fine Tuning and Administration
15600 There are several options which can be set for any jail, and various ways of combining a host DragonFly system with jails, to produce higher level applications. This section presents some of the options available for tuning the behavior and security restrictions implemented by a jail installation.
15602 ## System tools for jail tuning in DragonFly
15604 Fine tuning of a jail's configuration is mostly done by setting [sysctl(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=sysctl§ion=8) variables. A special subtree of sysctl exists as a basis for organizing all the relevant options: the ***securityjail**** hierarchy of DragonFly kernel options. Here is a list of the main jail-related sysctls, complete with their default value. Names should be self-explanatory, but for more information about them, please refer to the [jail(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=jail§ion=8) and [sysctl(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=sysctl§ion=8) manual pages.
15606 * jail.set_hostname_allowed: 1
15608 * jail.socket_unixiproute_only: 1
15610 * jail.sysvipc_allowed: 0
15612 * jail.enforce_statfs: 2
15614 * jail.allow_raw_sockets: 0
15616 * jail.chflags_allowed: 0
15620 These variables can be used by the system administrator of the host system to add or remove some of the limitations imposed by default on the root user. Note that there are some limitations which cannot be removed. The root user is not allowed to mount or unmount file systems from within a [jail(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=jail§ion=8). The root inside a jail may not set firewall rules or do many other administrative tasks which require modifications of in-kernel data, such as setting the securelevel of the kernel.
15624 The base system of DragonFly contains a basic set of tools for viewing information about the active jails, and attaching to a jail to run administrative commands. The [jls(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=jls§ion=8) and [jexec(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=jexec§ion=8) commands are part of the base DragonFly system, and can be used to perform the following simple tasks:
15626 * Print a list of active jails and their corresponding jail identifier (JID), IP address, hostname and path.
15628 * Attach to a running jail, from its host system, and run a command inside the jail or perform administrative tasks inside the jail itself. This is especially useful when the root user wants to cleanly shut down a jail. The [jexec(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=jexec§ion=8) utility can also be used to start a shell in a jail to do administration in it; for example:
15634 ***This Page is under constructions. New software are being added regularly.***
15635 **Follow the links below to see how to make corresponding software work on DragonFly**
15642 [FTP Server](http://www.dragonflybsd.org/docs/newhandbook/FTP/)
15644 ## Installing flash player on firefox.
15646 The Flash plugin is distributed by Adobe in **binary form only**. Adobe does not provide a native DragonFlyBSD plugin, but there is a Linux plugin which you can use under Linux emulation. Linux emulation software is installed from **pkgsrc** and is tested to be working fine on x86 Platform. The steps are
15648 ### Configure Linux Support
15650 # echo "linux_load=yes" >> /boot/loader.conf
15651 # echo "linux_enable=yes" >> /etc/rc.conf
15652 # echo "proc /compat/linux/proc linprocfs rw 0 0" >> /etc/fstab
15654 **Reboot DragonFly** ( not necessarry but easier for new users ) so that Linux Emulation is loaded to the kernel and configured correctly.
15656 ### Install multimedia/libflashsupport from pkgsrc.
15658 # cd /usr/pkgsrc/multimedia/libflashsupport
15661 This will get you all packages needed for Linux Emulation. Currently the Linux Emulation package installs software from [Suse 10]( http://ftp.hosteurope.de/mirror/ftp.opensuse.org/discontinued/10.0/suse/i586/) distribution. You could see the list of packages installed using pkg_info.
15663 # pkg_info |grep suse
15664 suse_openssl-10.0nb5 Linux compatibility package for OpenSSL
15665 suse_gtk2-10.0nb4 Linux compatibility package for GTK+-2.x
15666 suse_gtk-10.0nb2 Linux compatibility package for GTK+-1.x
15667 suse_libjpeg-10.0nb2 Linux compatibility package for JPEG
15668 suse_base-10.0nb5 Linux compatibility package
15669 suse_slang-10.0nb3 Linux compatibility package for S-Lang
15670 suse_locale-10.0nb2 Linux compatibility package with locale files
15671 suse_fontconfig-10.0nb6 Linux compatibility package for fontconfig
15672 suse_libtiff-10.0nb4 Linux compatibility package for TIFF
15673 suse_openmotif-10.0nb2 Linux compatibility package for OpenMotif
15674 suse_libpng-10.0nb4 Linux compatibility package for PNG
15675 suse_libcups-10.0nb4 Linux compatibility package for CUPS
15676 suse_gdk-pixbuf-10.0nb3 Linux compatibility package for gdk-pixbuf
15677 suse_expat-10.0nb2 Linux compatibility package for expat
15678 suse_vmware-10.0nb2 Linux compatibility package to help run VMware
15679 suse_libxml2-10.0nb2 Linux compatibility package for libxml2
15680 suse_compat-10.0nb3 Linux compatibility package with old shared libraries
15681 suse_x11-10.0nb4 Linux compatibility package for X11
15682 suse_glx-10.0nb4 Linux compatibility package for OpenGL/Mesa
15683 suse_freetype2-10.0nb5 Linux compatibility package for freetype-2.x
15684 suse_aspell-10.0nb2 Linux compatibility package for aspell
15685 suse-10.0nb4 SUSE-based Linux binary emulation environment
15687 ### Install www/nspluginwrapper
15689 This will allow DragonFly to use the Linux Binary Flash Plugin
15691 # cd /usr/pkgsrc/www/nspluginwrapper
15694 ### Install multimedia/ns-flash
15696 This is the Linux Flash Plugin itself.
15698 # cd /usr/pkgsrc/multimedia/ns-flash
15699 # bmake NO_CHECKSUM=yes package
15701 You can check if the Flash plugin is installed right by.
15703 # /usr/pkg/bin/nspluginwrapper --list
15704 /usr/pkg/lib/netscape/plugins/npwrapper.libflashplayer.so
15705 Original plugin: /usr/pkg/lib/netscape/plugins/libflashplayer.so
15706 Wrapper version string: 1.2.2
15707 /usr/pkg/lib/netscape/plugins/npwrapper.libflashplayer.so
15708 Original plugin: /usr/pkg/lib/netscape/plugins/libflashplayer.so
15709 Wrapper version string: 1.2.2
15711 Don't worry if it is listed twice as above.
15713 Now Start Firefox and type "**about:plugins**" in the address bar and you should find the flash plugins listed as [shown in this Picture](http://leaf.dragonflybsd.org/~sgeorge/PICs/flash-plugin-in-firefox.png).
15715 You can watch Streaming Flash now.
15717 ## Chapter 18 Serial Communications
15720 ***Reorganized, and parts rewritten by Ivailo Mladenov. ***
15724 UNIX® has always had support for serial communications. In fact, the very first UNIX machines relied on serial lines for user input and output. Things have changed a lot from the days when the average ***terminal*** consisted of a 10-character-per-second serial printer and a keyboard. This chapter will cover some of the ways in which DragonFly uses serial communications.
15726 After reading this chapter, you will know:
15728 * How to connect terminals to your DragonFly system.
15730 * How to use a modem to dial out to remote hosts.
15732 * How to allow remote users to login to your system with a modem.
15734 * How to boot your system from a serial console.
15736 Before reading this chapter, you should:
15738 * Know how to configure and install a new kernel ([kernelconfig.html Chapter 10]).
15740 * Understand UNIX permissions and processes ([basics.html Chapter 3]).
15742 * Have access to the technical manual for the serial hardware (modem or multi-port card) that you would like to use with DragonFly.
15746 ## 18.1 Introduction
15748 ### 18.1.1 Terminology
15750 bps:: Bits per Second -- the rate at which data is transmitted;
15752 DTE:: Data Terminal Equipment -- for example, your computer;
15754 DCE:: Data Communications Equipment -- your modem;
15756 RS-232:: EIA standard for hardware serial communications.
15758 When talking about communications data rates, this section does not use the term ***baud***. Baud refers to the number of electrical state transitions that may be made in a period of time, while ***bps*** (bits per second) is the ***correct*** term to use (at least it does not seem to bother the curmudgeons quite as much).
15760 ### 18.1.2 Cables and Ports
15762 To connect a modem or terminal to your DragonFly system, you will need a serial port on your computer and the proper cable to connect to your serial device. If you are already familiar with your hardware and the cable it requires, you can safely skip this section.
15764 #### 18.1.2.1 Cables
15766 There are several different kinds of serial cables. The two most common types for our purposes are null-modem cables and standard (***straight***) RS-232 cables. The documentation for your hardware should describe the type of cable required.
15768 ##### 18.1.2.1.1 Null-modem Cables
15770 A null-modem cable passes some signals, such as ***signal ground***, straight through, but switches other signals. For example, the ***send data*** pin on one end goes to the ***receive data*** pin on the other end.
15772 If you like making your own cables, you can construct a null-modem cable for use with terminals. This table shows the RS-232C signal names and the pin numbers on a DB-25 connector.
15775 | Signal | Pin # | | Pin # | Signal
15776 SG | 7 | connects to | 7 | SG
15777 TxD | 2 | connects to | 3 | RxD
15778 RxD | 3 | connects to | 2 | TxD
15779 RTS | 4 | connects to | 5 | CTS
15780 CTS | 5 | connects to | 4 | RTS
15781 DTR | 20 | connects to | 6 | DSR
15782 DCD | 8 | | 6 | DSR
15783 DSR | 6 | connects to | 20 | DTR |
15787 **Note:** Connect ***Data Set Ready*** (DSR) and ***Data Carrier Detect*** (DCD) internally in the connector hood, and then to ***Data Terminal Ready*** (DTR) in the remote hood.
15789 ##### 18.1.2.1.2 Standard RS-232C Cables
15791 A standard serial cable passes all the RS-232C signals straight-through. That is, the ***send data*** pin on one end of the cable goes to the ***send data*** pin on the other end. This is the type of cable to use to connect a modem to your DragonFly system, and is also appropriate for some terminals.
15793 #### 18.1.2.2 Ports
15795 Serial ports are the devices through which data is transferred between the DragonFly host computer and the terminal. This section describes the kinds of ports that exist and how they are addressed in DragonFly.
15797 ##### 18.1.2.2.1 Kinds of Ports
15799 Several kinds of serial ports exist. Before you purchase or construct a cable, you need to make sure it will fit the ports on your terminal and on the DragonFly system.
15801 Most terminals will have DB25 ports. Personal computers, including PCs running DragonFly, will have DB25 or DB9 ports. If you have a multiport serial card for your PC, you may have RJ-12 or RJ-45 ports.
15803 See the documentation that accompanied the hardware for specifications on the kind of port in use. A visual inspection of the port often works too.
15805 ##### 18.1.2.2.2 Port Names
15807 In DragonFly, you access each serial port through an entry in the `/dev` directory. There are two different kinds of entries:
15809 * Call-in ports are named `/dev/ttyd`***N****** where `***N***` is the port number, starting from zero. Generally, you use the call-in port for terminals. Call-in ports require that the serial line assert the data carrier detect (DCD) signal to work correctly.
15811 * Call-out ports are named `/dev/cuaa`***N******. You usually do not use the call-out port for terminals, just for modems. You may use the call-out port if the serial cable or the terminal does not support the carrier detect signal.
15813 If you have connected a terminal to the first serial port (`COM1` in MS-DOS®), then you will use `/dev/ttyd0` to refer to the terminal. If the terminal is on the second serial port (also known as `COM2`), use `/dev/ttyd1`, and so forth.
15815 ### 18.1.3 Kernel Configuration
15817 DragonFly supports four serial ports by default. In the MS-DOS world, these are known as `COM1`, `COM2`, `COM3`, and `COM4`. DragonFly currently supports ***dumb*** multiport serial interface cards, such as the BocaBoard 1008 and 2016, as well as more intelligent multi-port cards such as those made by Digiboard and Stallion Technologies. However, the default kernel only looks for the standard COM ports.
15819 To see if your kernel recognizes any of your serial ports, watch for messages while the kernel is booting, or use the `/sbin/dmesg` command to replay the kernel's boot messages. In particular, look for messages that start with the characters `sio`.
15821 **Tip:** To view just the messages that have the word `sio`, use the command:
15825 # /sbin/dmesg | grep 'sio'
15827 For example, on a system with four serial ports, these are the serial-port specific kernel boot messages:
15831 sio0 at 0x3f8-0x3ff irq 4 on isa
15835 sio1 at 0x2f8-0x2ff irq 3 on isa
15839 sio2 at 0x3e8-0x3ef irq 5 on isa
15843 sio3 at 0x2e8-0x2ef irq 9 on isa
15847 If your kernel does not recognize all of your serial ports, you will probably need to configure a custom DragonFly kernel for your system. For detailed information on configuring your kernel, please see [kernelconfig.html Chapter 12].
15849 The relevant device lines for your kernel configuration file would look like this:
15853 device sio0 at isa? port IO_COM1 irq 4
15855 device sio1 at isa? port IO_COM2 irq 3
15857 device sio2 at isa? port IO_COM3 irq 5
15859 device sio3 at isa? port IO_COM4 irq 9
15861 **Note:** `port IO_COM1` is a substitution for `port 0x3f8`, `IO_COM2` is `0x2f8`, `IO_COM3` is `0x3e8`, and `IO_COM4` is `0x2e8`, which are fairly common port addresses for their respective serial ports; interrupts 4, 3, 5, and 9 are fairly common interrupt request lines. Also note that regular serial ports ***cannot*** share interrupts on ISA-bus PCs (multiport boards have on-board electronics that allow all the 16550A's on the board to share one or two interrupt request lines).
15863 ### 18.1.4 Device Special Files
15865 Most devices in the kernel are accessed through ***device special files***, which are located in the `/dev` directory. The `sio` devices are accessed through the `/dev/ttyd`***N****** (dial-in) and `/dev/cuaa`***N****** (call-out) devices. DragonFly also provides initialization devices (`/dev/ttyid`***N****** and `/dev/cuaia`***N******) and locking devices (`/dev/ttyld`***N****** and `/dev/cuala`***N******). The initialization devices are used to initialize communications port parameters each time a port is opened, such as `crtscts` for modems which use `RTS/CTS` signaling for flow control. The locking devices are used to lock flags on ports to prevent users or programs changing certain parameters; see the manual pages [termios(4)](http://leaf.dragonflybsd.org/cgi/web-man?command#termios§ion4), [sio(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=sio§ion=4), and [stty(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=stty§ion=1) for information on the terminal settings, locking and initializing devices, and setting terminal options, respectively.
15867 ### 18.1.5 Serial Port Configuration
15869 The `ttyd`***N****** (or `cuaa`***N******) device is the regular device you will want to open for your applications. When a process opens the device, it will have a default set of terminal I/O settings. You can see these settings with the command
15873 # stty -a -f /dev/ttyd1
15875 When you change the settings to this device, the settings are in effect until the device is closed. When it is reopened, it goes back to the default set. To make changes to the default set, you can open and adjust the settings of the ***initial state*** device. For example, to turn on `CLOCAL` mode, 8 bit communication, and `XON/XOFF` flow control by default for `ttyd5`, type:
15879 # stty -f /dev/ttyid5 clocal cs8 ixon ixoff
15881 System-wide initialization of the serial devices is controlled in `/etc/rc.serial`. This file affects the default settings of serial devices.
15883 To prevent certain settings from being changed by an application, make adjustments to the ***lock state*** device. For example, to lock the speed of `ttyd5` to 57600 bps, type:
15887 # stty -f /dev/ttyld5 57600
15889 Now, an application that opens `ttyd5` and tries to change the speed of the port will be stuck with 57600 bps.
15891 Naturally, you should make the initial state and lock state devices writable only by the `root` account.
15897 Terminals provide a convenient and low-cost way to access your DragonFly system when you are not at the computer's console or on a connected network. This section describes how to use terminals with DragonFly.
15899 ### 18.2.1 Uses and Types of Terminals
15901 The original UNIX® systems did not have consoles. Instead, people logged in and ran programs through terminals that were connected to the computer's serial ports. It is quite similar to using a modem and terminal software to dial into a remote system to do text-only work.
15903 Today's PCs have consoles capable of high quality graphics, but the ability to establish a login session on a serial port still exists in nearly every UNIX style operating system today; DragonFly is no exception. By using a terminal attached to an unused serial port, you can log in and run any text program that you would normally run on the console or in an `xterm` window in the X Window System.
15905 For the business user, you can attach many terminals to a DragonFly system and place them on your employees' desktops. For a home user, a spare computer such as an older IBM PC or a Macintosh® can be a terminal wired into a more powerful computer running DragonFly. You can turn what might otherwise be a single-user computer into a powerful multiple user system.
15907 For DragonFly, there are three kinds of terminals:
15909 * [ Dumb terminals](term.html#TERM-DUMB)
15911 * [ PCs acting as terminals](term.html#TERM-PCS)
15913 * [ X terminals](term.html#TERM-X)
15915 #### 18.2.1.1 Dumb Terminals
15917 Dumb terminals are specialized pieces of hardware that let you connect to computers over serial lines. They are called ***dumb*** because they have only enough computational power to display, send, and receive text. You cannot run any programs on them. It is the computer to which you connect them that has all the power to run text editors, compilers, email, games, and so forth.
15919 There are hundreds of kinds of dumb terminals made by many manufacturers, including Digital Equipment Corporation's VT-100 and Wyse's WY-75. Just about any kind will work with DragonFly. Some high-end terminals can even display graphics, but only certain software packages can take advantage of these advanced features.
15921 Dumb terminals are popular in work environments where workers do not need access to graphical applications such as those provided by the X Window System.
15923 #### 18.2.1.2 PCs Acting as Terminals
15925 If a [ dumb terminal](term.html#TERM-DUMB) has just enough ability to display, send, and receive text, then certainly any spare personal computer can be a dumb terminal. All you need is the proper cable and some ***terminal emulation*** software to run on the computer.
15927 Such a configuration is popular in homes. For example, if your spouse is busy working on your DragonFly system's console, you can do some text-only work at the same time from a less powerful personal computer hooked up as a terminal to the DragonFly system.
15929 #### 18.2.1.3 X Terminals
15931 X terminals are the most sophisticated kind of terminal available. Instead of connecting to a serial port, they usually connect to a network like Ethernet. Instead of being relegated to text-only applications, they can display any X application.
15933 We introduce X terminals just for the sake of completeness. However, this chapter does ***not*** cover setup, configuration, or use of X terminals.
15935 ### 18.2.2 Configuration
15937 This section describes what you need to configure on your DragonFly system to enable a login session on a terminal. It assumes you have already configured your kernel to support the serial port to which the terminal is connected--and that you have connected it.
15939 Recall from [boot.html Chapter 10] that the `init` process is responsible for all process control and initialization at system startup. One of the tasks performed by `init` is to read the `/etc/ttys` file and start a `getty` process on the available terminals. The `getty` process is responsible for reading a login name and starting the `login` program.
15941 Thus, to configure terminals for your DragonFly system the following steps should be taken as `root`:
15943 1. Add a line to `/etc/ttys` for the entry in the `/dev` directory for the serial port if it is not already there.
15945 1. Specify that `/usr/libexec/getty` be run on the port, and specify the appropriate `***getty***` type from the `/etc/gettytab` file.
15947 1. Specify the default terminal type.
15949 1. Set the port to ***on.***
15951 1. Specify whether the port should be ***secure.***
15953 1. Force `init` to reread the `/etc/ttys` file.
15955 As an optional step, you may wish to create a custom `***getty***` type for use in step 2 by making an entry in `/etc/gettytab`. This chapter does not explain how to do so; you are encouraged to see the [gettytab(5)](http://leaf.dragonflybsd.org/cgi/web-man?command#gettytab&section5) and the [getty(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=getty&section=8) manual pages for more information.
15957 #### 18.2.2.1 Adding an Entry to `/etc/ttys`
15959 The `/etc/ttys` file lists all of the ports on your DragonFly system where you want to allow logins. For example, the first virtual console `ttyv0` has an entry in this file. You can log in on the console using this entry. This file also contains entries for the other virtual consoles, serial ports, and pseudo-ttys. For a hardwired terminal, just list the serial port's `/dev` entry without the `/dev` part (for example, `/dev/ttyv0` would be listed as `ttyv0`).
15961 A default DragonFly install includes an `/etc/ttys` file with support for the first four serial ports: `ttyd0` through `ttyd3`. If you are attaching a terminal to one of those ports, you do not need to add another entry.
15963 **Example 17-1. Adding Terminal Entries to `/etc/ttys`**
15965 Suppose we would like to connect two terminals to the system: a Wyse-50 and an old 286 IBM PC running **Procomm** terminal software emulating a VT-100 terminal. We connect the Wyse to the second serial port and the 286 to the sixth serial port (a port on a multiport serial card). The corresponding entries in the `/etc/ttys` file would look like this:
15969 ttyd1./imagelib/callouts/1.png "/usr/libexec/getty std.38400"./imagelib/callouts/2.png wy50./imagelib/callouts/3.png on./imagelib/callouts/4.png insecure./imagelib/callouts/5.png
15971 ttyd5 "/usr/libexec/getty std.19200" vt100 on insecure
15975 [ ./imagelib/callouts/1.png](term.html#CO-TTYS-LINE1COL1):: The first field normally specifies the name of the terminal special file as it is found in `/dev`.[ ./imagelib/callouts/2.png](term.html#CO-TTYS-LINE1COL2):: The second field is the command to execute for this line, which is usually [getty(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#getty&section8). `getty` initializes and opens the line, sets the speed, prompts for a user name and then executes the [login(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=login&section=1) program.The `getty` program accepts one (optional) parameter on its command line, the `***getty***` type. A `***getty***` type configures characteristics on the terminal line, like bps rate and parity. The `getty` program reads these characteristics from the file `/etc/gettytab`.The file `/etc/gettytab` contains lots of entries for terminal lines both old and new. In almost all cases, the entries that start with the text `std` will work for hardwired terminals. These entries ignore parity. There is a `std` entry for each bps rate from 110 to 115200. Of course, you can add your own entries to this file. The [gettytab(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=gettytab&section=5) manual page provides more information.When setting the `***getty***` type in the `/etc/ttys` file, make sure that the communications settings on the terminal match.For our example, the Wyse-50 uses no parity and connects at 38400 bps. The 286 PC uses no parity and connects at 19200 bps.[ ./imagelib/callouts/3.png](term.html#CO-TTYS-LINE1COL3):: The third field is the type of terminal usually connected to that tty line. For dial-up ports, `unknown` or `dialup` is typically used in this field since users may dial up with practically any type of terminal or software. For hardwired terminals, the terminal type does not change, so you can put a real terminal type from the [termcap(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=termcap&section=5) database file in this field.For our example, the Wyse-50 uses the real terminal type while the 286 PC running **Procomm** will be set to emulate at VT-100.[ ./imagelib/callouts/4.png](term.html#CO-TTYS-LINE1COL4):: The fourth field specifies if the port should be enabled. Putting `on` here will have the `init` process start the program in the second field, `getty`. If you put `off` in this field, there will be no `getty`, and hence no logins on the port.[ ./imagelib/callouts/5.png](term.html#CO-TTYS-LINE1COL5):: The final field is used to specify whether the port is secure. Marking a port as secure means that you trust it enough to allow the `root` account (or any account with a user ID of 0) to login from that port. Insecure ports do not allow `root` logins. On an insecure port, users must login from unprivileged accounts and then use [su(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=su&section=1) or a similar mechanism to gain superuser privileges.It is highly recommended that you use ***insecure*** even for terminals that are behind locked doors. It is quite easy to login and use `su` if you need superuser privileges.
15977 #### 18.2.2.2 Force `init` to Reread `/etc/ttys`
15979 After making the necessary changes to the `/etc/ttys` file you should send a SIGHUP (hangup) signal to the `init` process to force it to re-read its configuration file. For example:
15985 **Note:** `init` is always the first process run on a system, therefore it will always have PID 1.
15987 If everything is set up correctly, all cables are in place, and the terminals are powered up, then a `getty` process should be running on each terminal and you should see login prompts on your terminals at this point.
15989 ### 18.2.3 Troubleshooting Your Connection
15991 Even with the most meticulous attention to detail, something could still go wrong while setting up a terminal. Here is a list of symptoms and some suggested fixes.
15993 #### 18.2.3.1 No Login Prompt Appears
15995 Make sure the terminal is plugged in and powered up. If it is a personal computer acting as a terminal, make sure it is running terminal emulation software on the correct serial port.
15997 Make sure the cable is connected firmly to both the terminal and the DragonFly computer. Make sure it is the right kind of cable.
15999 Make sure the terminal and DragonFly agree on the bps rate and parity settings. If you have a video display terminal, make sure the contrast and brightness controls are turned up. If it is a printing terminal, make sure paper and ink are in good supply.
16001 Make sure that a `getty` process is running and serving the terminal. For example, to get a list of running `getty` processes with `ps`, type:
16005 # ps -axww|grep getty
16007 You should see an entry for the terminal. For example, the following display shows that a `getty` is running on the second serial port `ttyd1` and is using the `std.38400` entry in `/etc/gettytab`:
16011 22189 d1 Is+ 0:00.03 /usr/libexec/getty std.38400 ttyd1
16013 If no `getty` process is running, make sure you have enabled the port in `/etc/ttys`. Also remember to run `kill -HUP 1` after modifying the `ttys` file.
16015 If the `getty` process is running but the terminal still does not display a login prompt, or if it displays a prompt but will not allow you to type, your terminal or cable may not support hardware handshaking. Try changing the entry in `/etc/ttys` from `std.38400` to `3wire.38400` remember to run `kill -HUP 1` after modifying `/etc/ttys`). The `3wire` entry is similar to `std`, but ignores hardware handshaking. You may need to reduce the baud rate or enable software flow control when using `3wire` to prevent buffer overflows.
16017 #### 18.2.3.2 If Garbage Appears Instead of a Login Prompt
16019 Make sure the terminal and DragonFly agree on the bps rate and parity settings. Check the `getty` processes to make sure the correct `***getty***` type is in use. If not, edit `/etc/ttys` and run `kill -HUP 1`.
16021 #### 18.2.3.3 Characters Appear Doubled, the Password Appears When Typed
16023 Switch the terminal (or the terminal emulation software) from ***half duplex*** or ***local echo*** to ***full duplex.***
16027 ## 18.3 Dial-in Service
16029 Configuring your DragonFly system for dial-in service is very similar to connecting terminals except that you are dealing with modems instead of terminals.
16031 ### 18.3.1 External vs. Internal Modems
16033 External modems seem to be more convenient for dial-up, because external modems often can be semi-permanently configured via parameters stored in non-volatile RAM and they usually provide lighted indicators that display the state of important RS-232 signals. Blinking lights impress visitors, but lights are also very useful to see whether a modem is operating properly.
16035 Internal modems usually lack non-volatile RAM, so their configuration may be limited only to setting DIP switches. If your internal modem has any signal indicator lights, it is probably difficult to view the lights when the system's cover is in place.
16037 #### 18.3.1.1 Modems and Cables
16039 If you are using an external modem, then you will of course need the proper cable. A standard RS-232C serial cable should suffice as long as all of the normal signals are wired:
16041 * Transmitted Data (SD)
16043 * Received Data (RD)
16045 * Request to Send (RTS)
16047 * Clear to Send (CTS)
16049 * Data Set Ready (DSR)
16051 * Data Terminal Ready (DTR)
16053 * Carrier Detect (CD)
16055 * Signal Ground (SG)
16057 DragonFly needs the RTS and CTS signals for flow-control at speeds above 2400 bps, the CD signal to detect when a call has been answered or the line has been hung up, and the DTR signal to reset the modem after a session is complete. Some cables are wired without all of the needed signals, so if you have problems, such as a login session not going away when the line hangs up, you may have a problem with your cable.
16059 Like other UNIX® like operating systems, DragonFly uses the hardware signals to find out when a call has been answered or a line has been hung up and to hangup and reset the modem after a call. DragonFly avoids sending commands to the modem or watching for status reports from the modem. If you are familiar with connecting modems to PC-based bulletin board systems, this may seem awkward.
16061 ### 18.3.2 Serial Interface Considerations
16063 DragonFly supports NS8250-, NS16450-, NS16550-, and NS16550A-based EIA RS-232C (CCITT V.24) communications interfaces. The 8250 and 16450 devices have single-character buffers. The 16550 device provides a 16-character buffer, which allows for better system performance. (Bugs in plain 16550's prevent the use of the 16-character buffer, so use 16550A's if possible). Because single-character-buffer devices require more work by the operating system than the 16-character-buffer devices, 16550A-based serial interface cards are much preferred. If the system has many active serial ports or will have a heavy load, 16550A-based cards are better for low-error-rate communications.
16065 ### 18.3.3 Quick Overview
16067 As with terminals, `init` spawns a `getty` process for each configured serial port for dial-in connections. For example, if a modem is attached to `/dev/ttyd0`, the command `ps ax` might show this:
16071 4850 ?? I 0:00.09 /usr/libexec/getty V19200 ttyd0
16073 When a user dials the modem's line and the modems connect, the CD (Carrier Detect) line is reported by the modem. The kernel notices that carrier has been detected and completes `getty`'s open of the port. `getty` sends a login: prompt at the specified initial line speed. `getty` watches to see if legitimate characters are received, and, in a typical configuration, if it finds junk (probably due to the modem's connection speed being different than `getty`'s speed), `getty` tries adjusting the line speeds until it receives reasonable characters.
16075 After the user enters his/her login name, `getty` executes `/usr/bin/login`, which completes the login by asking for the user's password and then starting the user's shell.
16077 ### 18.3.4 Configuration Files
16079 There are three system configuration files in the `/etc` directory that you will probably need to edit to allow dial-up access to your DragonFly system. The first, `/etc/gettytab`, contains configuration information for the `/usr/libexec/getty` daemon. Second, `/etc/ttys` holds information that tells `/sbin/init` what `tty` devices should have `getty` processes running on them. Lastly, you can place port initialization commands in the `/etc/rc.serial` script.
16081 There are two schools of thought regarding dial-up modems on UNIX. One group likes to configure their modems and systems so that no matter at what speed a remote user dials in, the local computer-to-modem RS-232 interface runs at a locked speed. The benefit of this configuration is that the remote user always sees a system login prompt immediately. The downside is that the system does not know what a user's true data rate is, so full-screen programs like Emacs will not adjust their screen-painting methods to make their response better for slower connections.
16083 The other school configures their modems' RS-232 interface to vary its speed based on the remote user's connection speed. For example, V.32bis (14.4 Kbps) connections to the modem might make the modem run its RS-232 interface at 19.2 Kbps, while 2400 bps connections make the modem's RS-232 interface run at 2400 bps. Because `getty` does not understand any particular modem's connection speed reporting, `getty` gives a login: message at an initial speed and watches the characters that come back in response. If the user sees junk, it is assumed that they know they should press the Enter key until they see a recognizable prompt. If the data rates do not match, `getty` sees anything the user types as ***junk***, tries going to the next speed and gives the login: prompt again. This procedure can continue ad nauseam, but normally only takes a keystroke or two before the user sees a good prompt. Obviously, this login sequence does not look as clean as the former ***locked-speed*** method, but a user on a low-speed connection should receive better interactive response from full-screen programs.
16085 This section will try to give balanced configuration information, but is biased towards having the modem's data rate follow the connection rate.
16087 #### 18.3.4.1 `/etc/gettytab`
16089 `/etc/gettytab` is a [termcap(5)](http://leaf.dragonflybsd.org/cgi/web-man?command#termcap§ion5)-style file of configuration information for [getty(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=getty§ion=8). Please see the [gettytab(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=gettytab§ion=5) manual page for complete information on the format of the file and the list of capabilities.
16091 ##### 18.3.4.1.1 Locked-speed Config
16093 If you are locking your modem's data communications rate at a particular speed, you probably will not need to make any changes to `/etc/gettytab`.
16095 ##### 18.3.4.1.2 Matching-speed Config
16097 You will need to set up an entry in `/etc/gettytab` to give `getty` information about the speeds you wish to use for your modem. If you have a 2400 bps modem, you can probably use the existing `D2400` entry.
16103 # Fast dialup terminals, 2400/1200/300 rotary (can start either way)
16107 D2400|d2400|Fast-Dial-2400:\
16109 :nx#D1200:tc2400-baud:
16111 3|D1200|Fast-Dial-1200:\
16113 :nx#D300:tc1200-baud:
16115 5|D300|Fast-Dial-300:\
16117 :nx#D2400:tc300-baud:
16119 If you have a higher speed modem, you will probably need to add an entry in `/etc/gettytab`; here is an entry you could use for a 14.4 Kbps modem with a top interface speed of 19.2 Kbps:
16125 # Additions for a V.32bis Modem
16129 um|V300|High Speed Modem at 300,8-bit:\
16131 :nx#V19200:tcstd.300:
16133 un|V1200|High Speed Modem at 1200,8-bit:\
16135 :nx#V300:tcstd.1200:
16137 uo|V2400|High Speed Modem at 2400,8-bit:\
16139 :nx#V1200:tcstd.2400:
16141 up|V9600|High Speed Modem at 9600,8-bit:\
16143 :nx#V2400:tcstd.9600:
16145 uq|V19200|High Speed Modem at 19200,8-bit:\
16147 :nx#V9600:tcstd.19200:
16149 This will result in 8-bit, no parity connections.
16151 The example above starts the communications rate at 19.2 Kbps (for a V.32bis connection), then cycles through 9600 bps (for V.32), 2400 bps, 1200 bps, 300 bps, and back to 19.2 Kbps. Communications rate cycling is implemented with the `nx#` (***next table***) capability. Each of the lines uses a `tc` (***table continuation***) entry to pick up the rest of the ***standard*** settings for a particular data rate.
16153 If you have a 28.8 Kbps modem and/or you want to take advantage of compression on a 14.4 Kbps modem, you need to use a higher communications rate than 19.2 Kbps. Here is an example of a `gettytab` entry starting a 57.6 Kbps:
16159 # Additions for a V.32bis or V.34 Modem
16161 # Starting at 57.6 Kbps
16165 vm|VH300|Very High Speed Modem at 300,8-bit:\
16167 :nx#VH57600:tcstd.300:
16169 vn|VH1200|Very High Speed Modem at 1200,8-bit:\
16171 :nx#VH300:tcstd.1200:
16173 vo|VH2400|Very High Speed Modem at 2400,8-bit:\
16175 :nx#VH1200:tcstd.2400:
16177 vp|VH9600|Very High Speed Modem at 9600,8-bit:\
16179 :nx#VH2400:tcstd.9600:
16181 vq|VH57600|Very High Speed Modem at 57600,8-bit:\
16183 :nx#VH9600:tcstd.57600:
16185 If you have a slow CPU or a heavily loaded system and do not have 16550A-based serial ports, you may receive ***`sio`*** ***silo*** errors at 57.6 Kbps.
16187 #### 18.3.4.2 `/etc/ttys`
16189 Configuration of the `/etc/ttys` file was covered in [ Example 17-1](term.html#EX-ETC-TTYS). Configuration for modems is similar but we must pass a different argument to `getty` and specify a different terminal type. The general format for both locked-speed and matching-speed configurations is:
16193 ttyd0 "/usr/libexec/getty `***xxx***`" dialup on
16195 The first item in the above line is the device special file for this entry -- `ttyd0` means `/dev/ttyd0` is the file that this `getty` will be watching. The second item, `"/usr/libexec/getty `***xxx***`"` (`***xxx***` will be replaced by the initial `gettytab` capability) is the process `init` will run on the device. The third item, `dialup`, is the default terminal type. The fourth parameter, `on`, indicates to `init` that the line is operational. There can be a fifth parameter, `secure`, but it should only be used for terminals which are physically secure (such as the system console).
16197 The default terminal type (`dialup` in the example above) may depend on local preferences. `dialup` is the traditional default terminal type on dial-up lines so that users may customize their login scripts to notice when the terminal is `dialup` and automatically adjust their terminal type. However, the author finds it easier at his site to specify `vt102` as the default terminal type, since the users just use VT102 emulation on their remote systems.
16199 After you have made changes to `/etc/ttys`, you may send the `init` process a HUP signal to re-read the file. You can use the command
16205 to send the signal. If this is your first time setting up the system, you may want to wait until your modem(s) are properly configured and connected before signaling `init`.
16207 ##### 18.3.4.2.1 Locked-speed Config
16209 For a locked-speed configuration, your `ttys` entry needs to have a fixed-speed entry provided to `getty`. For a modem whose port speed is locked at 19.2 Kbps, the `ttys` entry might look like this:
16213 ttyd0 "/usr/libexec/getty std.19200" dialup on
16215 If your modem is locked at a different data rate, substitute the appropriate value for `std.`***speed****** instead of `std.19200`. Make sure that you use a valid type listed in `/etc/gettytab`.
16217 ##### 18.3.4.2.2 Matching-speed Config
16219 In a matching-speed configuration, your `ttys` entry needs to reference the appropriate beginning ***auto-baud*** (sic) entry in `/etc/gettytab`. For example, if you added the above suggested entry for a matching-speed modem that starts at 19.2 Kbps (the `gettytab` entry containing the `V19200` starting point), your `ttys` entry might look like this:
16223 ttyd0 "/usr/libexec/getty V19200" dialup on
16225 #### 18.3.4.3 `/etc/rc.serial`
16227 High-speed modems, like V.32, V.32bis, and V.34 modems, need to use hardware (`RTS/CTS`) flow control. You can add `stty` commands to `/etc/rc.serial` to set the hardware flow control flag in the DragonFly kernel for the modem ports.
16229 For example to set the `termios` flag `crtscts` on serial port #1's (`COM2`) dial-in and dial-out initialization devices, the following lines could be added to `/etc/rc.serial`:
16233 # Serial port initial configuration
16235 stty -f /dev/ttyid1 crtscts
16237 stty -f /dev/cuaia1 crtscts
16239 ### 18.3.5 Modem Settings
16241 If you have a modem whose parameters may be permanently set in non-volatile RAM, you will need to use a terminal program (such as Telix under MS-DOS® or `tip` under DragonFly) to set the parameters. Connect to the modem using the same communications speed as the initial speed `getty` will use and configure the modem's non-volatile RAM to match these requirements:
16243 * CD asserted when connected
16245 * DTR asserted for operation; dropping DTR hangs up line and resets modem
16247 * CTS transmitted data flow control
16249 * Disable XON/XOFF flow control
16251 * RTS received data flow control
16253 * Quiet mode (no result codes)
16257 Please read the documentation for your modem to find out what commands and/or DIP switch settings you need to give it.
16259 For example, to set the above parameters on a U.S. Robotics® Sportster® 14,400 external modem, one could give these commands to the modem:
16265 AT&C1&D2&H1&I0&R2&W
16267 You might also want to take this opportunity to adjust other settings in the modem, such as whether it will use V.42bis and/or MNP5 compression.
16269 The U.S. Robotics Sportster 14,400 external modem also has some DIP switches that need to be set; for other modems, perhaps you can use these settings as an example:
16271 * Switch 1: UP -- DTR Normal
16273 * Switch 2: N/A (Verbal Result Codes/Numeric Result Codes)
16275 * Switch 3: UP -- Suppress Result Codes
16277 * Switch 4: DOWN -- No echo, offline commands
16279 * Switch 5: UP -- Auto Answer
16281 * Switch 6: UP -- Carrier Detect Normal
16283 * Switch 7: UP -- Load NVRAM Defaults
16285 * Switch 8: N/A (Smart Mode/Dumb Mode)
16287 Result codes should be disabled/suppressed for dial-up modems to avoid problems that can occur if `getty` mistakenly gives a login: prompt to a modem that is in command mode and the modem echoes the command or returns a result code. This sequence can result in a extended, silly conversation between `getty` and the modem.
16289 #### 18.3.5.1 Locked-speed Config
16291 For a locked-speed configuration, you will need to configure the modem to maintain a constant modem-to-computer data rate independent of the communications rate. On a U.S. Robotics Sportster 14,400 external modem, these commands will lock the modem-to-computer data rate at the speed used to issue the commands:
16299 #### 18.3.5.2 Matching-speed Config
16301 For a variable-speed configuration, you will need to configure your modem to adjust its serial port data rate to match the incoming call rate. On a U.S. Robotics Sportster 14,400 external modem, these commands will lock the modem's error-corrected data rate to the speed used to issue the commands, but allow the serial port rate to vary for non-error-corrected connections:
16308 #### 18.3.5.3 Checking the Modem's Configuration
16310 Most high-speed modems provide commands to view the modem's current operating parameters in a somewhat human-readable fashion. On the U.S. Robotics Sportster 14,400 external modems, the command `ATI5` displays the settings that are stored in the non-volatile RAM. To see the true operating parameters of the modem (as influenced by the modem's DIP switch settings), use the commands `ATZ` and then `ATI4`.
16312 If you have a different brand of modem, check your modem's manual to see how to double-check your modem's configuration parameters.
16314 ### 18.3.6 Troubleshooting
16316 Here are a few steps you can follow to check out the dial-up modem on your system.
16318 #### 18.3.6.1 Checking Out the DragonFly System
16320 Hook up your modem to your DragonFly system, boot the system, and, if your modem has status indication lights, watch to see whether the modem's DTR indicator lights when the login: prompt appears on the system's console -- if it lights up, that should mean that DragonFly has started a `getty` process on the appropriate communications port and is waiting for the modem to accept a call.
16322 If the DTR indicator does not light, login to the DragonFly system through the console and issue a `ps ax` to see if DragonFly is trying to run a `getty` process on the correct port. You should see lines like these among the processes displayed:
16326 114 ?? I 0:00.10 /usr/libexec/getty V19200 ttyd0
16328 115 ?? I 0:00.10 /usr/libexec/getty V19200 ttyd1
16330 If you see something different, like this:
16334 114 d0 I 0:00.10 /usr/libexec/getty V19200 ttyd0
16336 and the modem has not accepted a call yet, this means that `getty` has completed its open on the communications port. This could indicate a problem with the cabling or a mis-configured modem, because `getty` should not be able to open the communications port until CD (carrier detect) has been asserted by the modem.
16338 If you do not see any `getty` processes waiting to open the desired `ttyd`***N****** port, double-check your entries in `/etc/ttys` to see if there are any mistakes there. Also, check the log file `/var/log/messages` to see if there are any log messages from `init` or `getty` regarding any problems. If there are any messages, triple-check the configuration files `/etc/ttys` and `/etc/gettytab`, as well as the appropriate device special files `/dev/ttydN`, for any mistakes, missing entries, or missing device special files.
16340 #### 18.3.6.2 Try Dialing In
16342 Try dialing into the system; be sure to use 8 bits, no parity, and 1 stop bit on the remote system. If you do not get a prompt right away, or get garbage, try pressing Enter about once per second. If you still do not see a login: prompt after a while, try sending a `BREAK`. If you are using a high-speed modem to do the dialing, try dialing again after locking the dialing modem's interface speed (via `AT&B1` on a U.S. Robotics Sportster modem, for example).
16344 If you dial but the modem on the DragonFly system will not answer, make sure that the modem is configured to answer the phone when DTR is asserted. If the modem seems to be configured correctly, verify that the DTR line is asserted by checking the modem's indicator lights (if it has any).
16346 If you have gone over everything several times and it still does not work, take a break and come back to it later. If it still does not work, perhaps you can send an electronic mail message to the [DragonFly User related mailing list](http://leaf.dragonflybsd.org/mailarchive/) describing your modem and your problem, and the good folks on the list will try to help.
16349 ## 18.4 Dial-out Service
16351 The following are tips for getting your host to be able to connect over the modem to another computer. This is appropriate for establishing a terminal session with a remote host.
16353 This is useful to log onto a BBS.
16355 This kind of connection can be extremely helpful to get a file on the Internet if you have problems with PPP. If you need to FTP something and PPP is broken, use the terminal session to FTP it. Then use zmodem to transfer it to your machine.
16357 ### 18.4.1 My Stock Hayes Modem Is Not Supported, What Can I Do?
16359 Actually, the manual page for `tip` is out of date. There is a generic Hayes dialer already built in. Just use `at=hayes` in your `/etc/remote` file.
16361 The Hayes driver is not smart enough to recognize some of the advanced features of newer modems--messages like `BUSY`, `NO DIALTONE`, or `CONNECT 115200` will just confuse it. You should turn those messages off when you use `tip` (using `ATX0&W`).
16363 Also, the dial timeout for `tip` is 60 seconds. Your modem should use something less, or else tip will think there is a communication problem. Try `ATS7=45&W`.
16365 **Note:** As shipped, `tip` does not yet support Hayes modems fully. The solution is to edit the file `tipconf.h` in the directory `/usr/src/usr.bin/tip/tip`. Obviously you need the source distribution to do this.
16367 Edit the line `#define HAYES 0` to `#define HAYES 1`. Then `make` and `make install`. Everything works nicely after that.
16369 ### 18.4.2 How Am I Expected to Enter These AT Commands?
16371 Make what is called a ***direct*** entry in your `/etc/remote` file. For example, if your modem is hooked up to the first serial port, `/dev/cuaa0`, then put in the following line:
16375 cuaa0:dv#/dev/cuaa0:br#19200:panone
16377 Use the highest bps rate your modem supports in the br capability. Then, type `tip cuaa0` and you will be connected to your modem.
16379 Or use `cu` as `root` with the following command:
16383 # cu -l`***line***` -s`***speed***`
16385 `***line***` is the serial port (e.g.`/dev/cuaa0`) and `***speed***` is the speed (e.g.`57600`). When you are done entering the AT commands hit **~.** to exit.
16387 ### 18.4.3 The `@` Sign for the pn Capability Does Not Work!
16389 The `@` sign in the phone number capability tells tip to look in `/etc/phones` for a phone number. But the `@` sign is also a special character in capability files like `/etc/remote`. Escape it with a backslash:
16395 ### 18.4.4 How Can I Dial a Phone Number on the Command Line?
16397 Put what is called a ***generic*** entry in your `/etc/remote` file. For example:
16401 tip115200|Dial any phone number at 115200 bps:\
16403 :dv#/dev/cuaa0:br#115200:athayes:pa=none:du:
16405 tip57600|Dial any phone number at 57600 bps:\
16407 :dv#/dev/cuaa0:br#57600:athayes:pa=none:du:
16409 Then you can do things like:
16413 # tip -115200 5551234
16415 If you prefer `cu` over `tip`, use a generic `cu` entry:
16419 cu115200|Use cu to dial any number at 115200bps:\
16421 :dv#/dev/cuaa1:br#57600:athayes:pa=none:du:
16427 # cu 5551234 -s 115200
16429 ### 18.4.5 Do I Have to Type in the bps Rate Every Time I Do That?
16431 Put in an entry for `tip1200` or `cu1200`, but go ahead and use whatever bps rate is appropriate with the br capability. `tip` thinks a good default is 1200 bps which is why it looks for a `tip1200` entry. You do not have to use 1200 bps, though.
16433 ### 18.4.6 I Access a Number of Hosts Through a Terminal Server
16435 Rather than waiting until you are connected and typing `CONNECT <host>` each time, use tip's `cm` capability. For example, these entries in `/etc/remote`:
16439 pain|pain.deep13.com|Forrester's machine:\
16441 :cm#CONNECT pain\n:tcdeep13:
16443 muffin|muffin.deep13.com|Frank's machine:\
16445 :cm#CONNECT muffin\n:tcdeep13:
16447 deep13:Gizmonics Institute terminal server:\
16449 :dv#/dev/cuaa2:br#38400:athayes:du:pa=none:pn=5551234:
16451 will let you type `tip pain` or `tip muffin` to connect to the hosts pain or muffin, and `tip deep13` to get to the terminal server.
16453 ### 18.4.7 Can Tip Try More Than One Line for Each Site?
16455 This is often a problem where a university has several modem lines and several thousand students trying to use them.
16457 Make an entry for your university in `/etc/remote` and use `@` for the `pn` capability:
16467 :dv#/dev/cuaa3:br#9600:atcourier:du:pa=none:
16469 Then, list the phone numbers for the university in `/etc/phones`:
16473 big-university 5551111
16475 big-university 5551112
16477 big-university 5551113
16479 big-university 5551114
16481 `tip` will try each one in the listed order, then give up. If you want to keep retrying, run `tip` in a while loop.
16483 ### 18.4.8 Why Do I Have to Hit **Ctrl** + **P** Twice to Send **Ctrl** + **P** Once?
16485 **Ctrl** + **P** is the default ***force*** character, used to tell `tip` that the next character is literal data. You can set the force character to any other character with the `~s` escape, which means ***set a variable.***
16487 Type `~sforce=`***single-char****** followed by a newline. `***single-char***` is any single character. If you leave out `***single-char***`, then the force character is the nul character, which you can get by typing **Ctrl** + **2** or **Ctrl** + **Space** . A pretty good value for `***single-char***` is **Shift** + **Ctrl** + **6** , which is only used on some terminal servers.
16489 You can have the force character be whatever you want by specifying the following in your `$HOME/.tiprc` file:
16493 force=<single-char>
16495 ### 18.4.9 Suddenly Everything I Type Is in Upper Case??
16497 You must have pressed **Ctrl** + **A** , `tip`'s ***raise character,*** specially designed for people with broken caps-lock keys. Use `~s` as above and set the variable `raisechar` to something reasonable. In fact, you can set it to the same as the force character, if you never expect to use either of these features.
16499 Here is a sample .tiprc file perfect for **Emacs** users who need to type **Ctrl** + **2** and **Ctrl** + **A** a lot:
16507 The ^^ is **Shift** + **Ctrl** + **6** .
16509 ### 18.4.10 How Can I Do File Transfers with `tip`?
16511 If you are talking to another UNIX® system, you can send and receive files with `~p` (put) and `~t` (take). These commands run `cat` and `echo` on the remote system to accept and send files. The syntax is:
16513 `~p` local-file [remote-file]
16515 `~t` remote-file [local-file]
16517 There is no error checking, so you probably should use another protocol, like zmodem.
16519 ### 18.4.11 How Can I Run zmodem with `tip`?
16521 To receive files, start the sending program on the remote end. Then, type `~C rz` to begin receiving them locally.
16523 To send files, start the receiving program on the remote end. Then, type `~C sz `***files****** to send them to the remote system.
16527 ## 18.5 Setting Up the Serial Console
16529 ### 18.5.1 Introduction
16531 DragonFly has the ability to boot on a system with only a dumb terminal on a serial port as a console. Such a configuration should be useful for two classes of people: system administrators who wish to install DragonFly on machines that have no keyboard or monitor attached, and developers who want to debug the kernel or device drivers.
16533 As described in [boot.html Chapter 10], DragonFly employs a three stage bootstrap. The first two stages are in the boot block code which is stored at the beginning of the DragonFly slice on the boot disk. The boot block will then load and run the boot loader (`/boot/loader`) as the third stage code.
16535 In order to set up the serial console you must configure the boot block code, the boot loader code and the kernel.
16537 ### 18.5.2 Serial Console Configuration, Terse Version
16539 This section assumes that you are using the default setup, know how to connect serial ports and just want a fast overview of a serial console. If you encounter difficulty with these steps, please see the more extensive explaination of all the options and advanced settings in [serialconsole-setup.html#SERIALCONSOLE-HOWTO Section 18.5.3].
16541 1. Connect the serial port. The serial console will be on COM1.
16543 1. `echo -h > /boot.config` to enable the serial console for the boot loader and kernel.
16545 1. Edit `/etc/ttys` and change `off` to `on` for the `ttyd0` entry. This enables a login prompt on the serial console, which mirrors how video consoles are typically setup.
16547 1. `shutdown -r now` will reboot the system with the serial console.
16549 ### 18.5.3 Serial Console Configuration
16551 1. Prepare a serial cable.
16553 You will need either a null-modem cable or a standard serial cable and a null-modem adapter. See [ Section 18.1.2](serial.html#SERIAL-CABLES-PORTS) for a discussion on serial cables.
16555 1. Unplug your keyboard.
16557 Most PC systems probe for the keyboard during the Power-On Self-Test (POST) and will generate an error if the keyboard is not detected. Some machines complain loudly about the lack of a keyboard and will not continue to boot until it is plugged in.
16559 If your computer complains about the error, but boots anyway, then you do not have to do anything special. (Some machines with Phoenix BIOS installed merely say ***`Keyboard failed`*** and continue to boot normally.)
16561 If your computer refuses to boot without a keyboard attached then you will have to configure the BIOS so that it ignores this error (if it can). Consult your motherboard's manual for details on how to do this.
16563 **Tip:** Setting the keyboard to ***Not installed*** in the BIOS setup does ***not*** mean that you will not be able to use your keyboard. All this does is tell the BIOS not to probe for a keyboard at power-on, so it will not complain if the keyboard is not plugged in. You can leave the keyboard plugged in even with this flag set to ***Not installed*** and the keyboard will still work.
16565 **Note:** If your system has a PS/2® mouse, chances are very good that you may have to unplug your mouse as well as your keyboard. This is because PS/2 mice share some hardware with the keyboard and leaving the mouse plugged in can fool the keyboard probe into thinking the keyboard is still there. In general, this is not a problem since the mouse is not much good without the keyboard anyway.
16567 1. Plug a dumb terminal into `COM1` (`sio0`).
16569 If you do not have a dumb terminal, you can use an old PC/XT with a modem program, or the serial port on another UNIX® box. If you do not have a `COM1` (`sio0`), get one. At this time, there is no way to select a port other than `COM1` for the boot blocks without recompiling the boot blocks. If you are already using `COM1` for another device, you will have to temporarily remove that device and install a new boot block and kernel once you get DragonFly up and running. (It is assumed that `COM1` will be available on a file/compute/terminal server anyway; if you really need `COM1` for something else (and you cannot switch that something else to `COM2` (`sio1`)), then you probably should not even be bothering with all this in the first place.)
16571 1. Make sure the configuration file of your kernel has appropriate flags set for `COM1` (`sio0`).
16573 Relevant flags are:
16575 `0x10`:: Enables console support for this unit. The other console flags are ignored unless this is set. Currently, at most one unit can have console support; the first one (in config file order) with this flag set is preferred. This option alone will not make the serial port the console. Set the following flag or use the `-h` option described below, together with this flag.`0x20`:: Forces this unit to be the console (unless there is another higher priority console), regardless of the `-h` option discussed below. This flag replaces the `COMCONSOLE` option in DragonFly versions 2.`***X***`. The flag `0x20` must be used together with the `0x10` flag.`0x40`:: Reserves this unit (in conjunction with `0x10`) and makes the unit unavailable for normal access. You should not set this flag to the serial port unit which you want to use as the serial console. This reserves this port for "low-level IO", i.e. kernel debugging.`0x80`:: This port will be used for remote kernel debugging.
16581 device sio0 at isa? port IO_COM1 flags 0x10 irq 4
16585 See the [sio(4)](http://leaf.dragonflybsd.org/cgi/web-man?command#sio§ion4) manual page for more details.
16587 If the flags were not set, you need to run UserConfig (on a different console) or recompile the kernel.
16589 1. Create `boot.config` in the root directory of the `a` partition on the boot drive.
16591 This file will instruct the boot block code how you would like to boot the system. In order to activate the serial console, you need one or more of the following options--if you want multiple options, include them all on the same line:
16593 `-h`:: Toggles internal and serial consoles. You can use this to switch console devices. For instance, if you boot from the internal (video) console, you can use `-h` to direct the boot loader and the kernel to use the serial port as its console device. Alternatively, if you boot from the serial port, you can use the `-h` to tell the boot loader and the kernel to use the video display as the console instead.`-D`:: Toggles single and dual console configurations. In the single configuration the console will be either the internal console (video display) or the serial port, depending on the state of the `-h` option above. In the dual console configuration, both the video display and the serial port will become the console at the same time, regardless of the state of the `-h` option. However, note that the dual console configuration takes effect only during the boot block is running. Once the boot loader gets control, the console specified by the `-h` option becomes the only console.`-P`:: Makes the boot block probe the keyboard. If no keyboard is found, the `-D` and `-h` options are automatically set.
16595 **Note:** Due to space constraints in the current version of the boot blocks, the `-P` option is capable of detecting extended keyboards only. Keyboards with less than 101 keys (and without F11 and F12 keys) may not be detected. Keyboards on some laptop computers may not be properly found because of this limitation. If this is the case with your system, you have to abandon using the `-P` option. Unfortunately there is no workaround for this problem.
16597 Use either the `-P` option to select the console automatically, or the `-h` option to activate the serial console.
16599 You may include other options described in [boot(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#boot§ion8) as well.
16601 The options, except for `-P`, will be passed to the boot loader (`/boot/loader`). The boot loader will determine which of the internal video or the serial port should become the console by examining the state of the `-h` option alone. This means that if you specify the `-D` option but not the `-h` option in `/boot.config`, you can use the serial port as the console only during the boot block; the boot loader will use the internal video display as the console.
16603 1. Boot the machine.
16605 When you start your DragonFly box, the boot blocks will echo the contents of `/boot.config` to the console. For example:
16615 The second line appears only if you put `-P` in `/boot.config` and indicates presence/absence of the keyboard. These messages go to either serial or internal console, or both, depending on the option in `/boot.config`.
16617 || Options || Message goes to ||
16619 || none || internal console ||
16621 || `-h` || serial console ||
16623 || `-D` || serial and internal consoles ||
16625 || `-Dh` || serial and internal consoles ||
16627 || `-P`, keyboard present || internal console ||
16629 || `-P`, keyboard absent || serial console ||
16631 After the above messages, there will be a small pause before the boot blocks continue loading the boot loader and before any further messages printed to the console. Under normal circumstances, you do not need to interrupt the boot blocks, but you may want to do so in order to make sure things are set up correctly.
16633 Hit any key, other than Enter, at the console to interrupt the boot process. The boot blocks will then prompt you for further action. You should now see something like:
16637 >> DragonFly/i386 BOOT
16639 Default: 0:ad(0,a)/boot/loader
16645 Verify the above message appears on either the serial or internal console or both, according to the options you put in `/boot.config`. If the message appears in the correct console, hit Enter to continue the boot process.
16647 If you want the serial console but you do not see the prompt on the serial terminal, something is wrong with your settings. In the meantime, you enter `-h` and hit Enter/Return (if possible) to tell the boot block (and then the boot loader and the kernel) to choose the serial port for the console. Once the system is up, go back and check what went wrong.
16649 After the boot loader is loaded and you are in the third stage of the boot process you can still switch between the internal console and the serial console by setting appropriate environment variables in the boot loader. See [serialconsole-setup.html#SERIALCONSOLE-LOADER Section 18.5.6].
16653 Here is the summary of various settings discussed in this section and the console eventually selected.
16655 #### 18.5.4.1 Case 1: You Set the Flags to 0x10 for `sio0`
16659 device sio0 at isa? port IO_COM1 flags 0x10 irq 4
16662 | Options in /boot.config | Console during boot blocks | Console during boot loader | Console in kernel
16663 nothing | internal | internal | internal
16664 `-h` | serial | serial | serial
16665 `-D` | serial and internal | internal | internal
16666 `-Dh` | serial and internal | serial | serial
16667 `-P`, keyboard present | internal | internal | internal
16668 `-P`, keyboard absent | serial and internal | serial | serial |
16672 #### 18.5.4.2 Case 2: You Set the Flags to 0x30 for sio0
16676 device sio0 at isa? port IO_COM1 flags 0x30 irq 4
16679 | Options in /boot.config | Console during boot blocks | Console during boot loader | Console in kernel
16680 nothing | internal | internal | serial
16681 `-h` | serial | serial | serial
16682 `-D` | serial and internal | internal | serial
16683 `-Dh` | serial and internal | serial | serial
16684 `-P`, keyboard present | internal | internal | serial
16685 `-P`, keyboard absent | serial and internal | serial | serial |
16689 ### 18.5.5 Tips for the Serial Console
16691 #### 18.5.5.1 Setting a Faster Serial Port Speed
16693 By default, the serial port settings are: 9600 baud, 8 bits, no parity, and 1 stop bit. If you wish to change the speed, you need to recompile at least the boot blocks. Add the following line to `/etc/make.conf` and compile new boot blocks:
16697 BOOT_COMCONSOLE_SPEED=19200
16699 If the serial console is configured in some other way than by booting with `-h`, or if the serial console used by the kernel is different from the one used by the boot blocks, then you must also add the following option to the kernel configuration file and compile a new kernel:
16703 options CONSPEED=19200
16705 #### 18.5.5.2 Using Serial Port Other Than `sio0` for the Console
16707 Using a port other than `sio0` as the console requires some recompiling. If you want to use another serial port for whatever reasons, recompile the boot blocks, the boot loader and the kernel as follows.
16709 1. Get the kernel source.
16711 1. Edit `/etc/make.conf` and set `BOOT_COMCONSOLE_PORT` to the address of the port you want to use (0x3F8, 0x2F8, 0x3E8 or 0x2E8). Only `sio0` through `sio3` (`COM1` through `COM4`) can be used; multiport serial cards will not work. No interrupt setting is needed.
16713 1. Create a custom kernel configuration file and add appropriate flags for the serial port you want to use. For example, if you want to make `sio1` (`COM2`) the console:
16717 device sio1 at isa? port IO_COM2 flags 0x10 irq 3
16725 device sio1 at isa? port IO_COM2 flags 0x30 irq 3
16729 The console flags for the other serial ports should not be set.
16731 1. Recompile and install the boot blocks and the boot loader:
16743 1. Rebuild and install the kernel.
16745 1. Write the boot blocks to the boot disk with [disklabel(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#disklabel§ion8) and boot from the new kernel.
16747 #### 18.5.5.3 Entering the DDB Debugger from the Serial Line
16749 If you wish to drop into the kernel debugger from the serial console (useful for remote diagnostics, but also dangerous if you generate a spurious BREAK on the serial port!) then you should compile your kernel with the following options:
16753 options BREAK_TO_DEBUGGER
16757 #### 18.5.5.4 Getting a Login Prompt on the Serial Console
16759 While this is not required, you may wish to get a ***login*** prompt over the serial line, now that you can see boot messages and can enter the kernel debugging session through the serial console. Here is how to do it.
16761 Open the file `/etc/ttys` with an editor and locate the lines:
16765 ttyd0 "/usr/libexec/getty std.9600" unknown off secure
16767 ttyd1 "/usr/libexec/getty std.9600" unknown off secure
16769 ttyd2 "/usr/libexec/getty std.9600" unknown off secure
16771 ttyd3 "/usr/libexec/getty std.9600" unknown off secure
16773 `ttyd0` through `ttyd3` corresponds to `COM1` through `COM4`. Change `off` to `on` for the desired port. If you have changed the speed of the serial port, you need to change `std.9600` to match the current setting, e.g. `std.19200`.
16775 You may also want to change the terminal type from `unknown` to the actual type of your serial terminal.
16777 After editing the file, you must `kill -HUP 1` to make this change take effect.
16779 ### 18.5.6 Changing Console from the Boot Loader
16781 Previous sections described how to set up the serial console by tweaking the boot block. This section shows that you can specify the console by entering some commands and environment variables in the boot loader. As the boot loader is invoked at the third stage of the boot process, after the boot block, the settings in the boot loader will override the settings in the boot block.
16783 #### 18.5.6.1 Setting Up the Serial Console
16785 You can easily specify the boot loader and the kernel to use the serial console by writing just one line in `/boot/loader.rc`:
16789 set console=comconsole
16791 This will take effect regardless of the settings in the boot block discussed in the previous section.
16793 You had better put the above line as the first line of `/boot/loader.rc` so as to see boot messages on the serial console as early as possible.
16795 Likewise, you can specify the internal console as:
16799 set console=vidconsole
16801 If you do not set the boot loader environment variable `console`, the boot loader, and subsequently the kernel, will use whichever console indicated by the `-h` option in the boot block.
16803 In versions 3.2 or later, you may specify the console in `/boot/loader.conf.local` or `/boot/loader.conf`, rather than in `/boot/loader.rc`. In this method your `/boot/loader.rc` should look like:
16807 include /boot/loader.4th
16811 Then, create `/boot/loader.conf.local` and put the following line there.
16823 **Note:** At the moment, the boot loader has no option equivalent to the `-P` option in the boot block, and there is no provision to automatically select the internal console and the serial console based on the presence of the keyboard.
16825 #### 18.5.6.2 Using a Serial Port Other Than `sio0` for the Console
16827 You need to recompile the boot loader to use a serial port other than `sio0` for the serial console. Follow the procedure described in [serialconsole-setup.html#SERIALCONSOLE-COM2 Section 18.5.5.2].
16831 The idea here is to allow people to set up dedicated servers that require no graphics hardware or attached keyboards. Unfortunately, while most systems will let you boot without a keyboard, there are quite a few that will not let you boot without a graphics adapter. Machines with AMI BIOSes can be configured to boot with no graphics adapter installed simply by changing the ***graphics adapter*** setting in the CMOS configuration to ***Not installed.***