wip: this is my version of the first 10 or so chapters of the handbook. this is not...
[ikiwiki.git] / docs / newhandbook / index.mdwn
1 ----
2
3
4
5 ## Preface 
6
7
8
9 ## Intended Audience 
10
11
12
13 The DragonFly newcomer will find that the first section of this book guides the user through the DragonFly installation process and gently introduces the concepts and conventions that underpin UNIX®. Working through this section requires little more than the desire to explore, and the ability to take on broad new concepts as they are introduced.
14
15
16
17 Once you have travelled this far, the second, far larger, section of the Handbook is a comprehensive reference to all manner of topics of interest to DragonFly system administrators. Some of these chapters may recommend that you do some prior reading, and this is noted in the synopsis at the beginning of each chapter.
18
19
20
21 For a list of additional sources of information, please see [Appendix B](bibliography.html).
22
23
24 <!-- Cut out of "Organization of This Book" -->
25
26
27
28 ## Conventions used in this book 
29
30
31
32 To provide a consistent and easy to read text, several conventions are followed throughout the book.
33
34
35
36 ### Typographic Conventions 
37
38
39
40 ***Italic***
41
42  :: An ***italic*** font is used for filenames, URLs, emphasized text, and the first usage of technical terms.
43
44
45
46 `Monospace`
47
48  :: A `monospaced` font is used for error messages, commands, environment variables, names of ports, hostnames, user names, group names, device names, variables, and code fragments.
49
50
51
52  **Bold** 
53
54  :: A  **bold**  font is used for applications, commands, and keys.
55
56
57
58 ### User Input 
59
60
61
62 Keys are shown in  **bold**  to stand out from other text. Key combinations that are meant to be typed simultaneously are shown with **+** between the keys, such as:
63
64
65
66  **Ctrl** + **Alt** + **Del** 
67
68
69
70 Meaning the user should type the  **Ctrl** ,  **Alt** ,and  **Del**  keys at the same time.
71
72
73
74 Keys that are meant to be typed in sequence will be separated with commas, for example:
75
76
77
78  **Ctrl** + **X** ,  **Ctrl** + **S** 
79
80
81
82 Would mean that the user is expected to type the  **Ctrl**  and  **X**  keys simultaneously and then to type the  **Ctrl**  and  **S**  keys simultaneously.
83
84
85
86 ### Examples 
87
88
89
90 Examples starting with # indicate a command that must be invoked as the superuser in DragonFly. You can login as `root` to type the command, or login as your normal account and use [su(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=su&section1) to gain superuser privileges.
91
92
93
94     
95
96     # dd if=kern.flp of=/dev/fd0
97
98
99
100
101
102 Examples starting with % indicate a command that should be invoked from a normal user account. Unless otherwise noted, C-shell syntax is used for setting environment variables and other shell commands.
103
104
105
106     
107
108     % top
109
110
111
112
113
114 Examples starting with `E:\>` indicate a MS-DOS® command. Unless otherwise noted, these commands may be executed from a ***Command Prompt*** window in a modern Microsoft® Windows® environment.
115
116
117
118     
119
120     E:\> tools\fdimage floppies\kern.flp A:
121
122
123
124
125
126 ## Acknowledgments 
127
128
129
130 The book you are holding represents the efforts of many hundreds of people around the world. Whether they sent in fixes for typos, or submitted complete chapters, all the contributions have been useful.
131
132
133
134 The DragonFly Handbook was originally built from an edition of the FreeBSD Handbook. The FreeBSD Handbook was created by the collective hard work of hundreds of people, and the DragonFly Documentation Team appreciates all their labor.
135
136
137
138 ----
139
140
141
142
143
144
145 # I. Getting Started 
146
147
148
149 This part of the DragonFly Handbook is for users and administrators who are new to DragonFly. These chapters:
150
151
152
153
154 * Introduce you to DragonFly.
155
156
157 * Guide you through the installation process.
158
159
160 * Teach you UNIX® basics and fundamentals.
161
162
163 * Show you how to install the wealth of third party applications available for DragonFly.
164
165
166 * Introduce you to X, the UNIX windowing system, and detail how to configure a desktop environment that makes you more productive.
167
168
169
170 We have tried to keep the number of forward references in the text to a minimum so that you can read this section of the Handbook from front to back with the minimum page flipping required.
171
172
173
174
175
176 ----
177
178
179
180 ## Chapter 1 Introduction 
181
182 ***Restructured, reorganized, and parts rewritten by Jim Mock. ***
183
184
185
186 ## 1.1 Synopsis 
187
188
189
190 Thank you for your interest in DragonFly! The following chapter covers various aspects of the DragonFly Project, such as its history, goals, development model, and so on.
191
192
193
194 After reading this chapter, you will know:
195
196
197
198
199 * How DragonFly relates to other computer operating systems.
200
201
202 * The history of the DragonFly Project.
203
204
205 * The goals of the DragonFly Project.
206
207
208 * The basics of the DragonFly open-source development model.
209
210
211 * And of course: where the name ***DragonFly*** comes from.
212
213
214
215
216
217
218 ----
219
220
221
222 # 1.2 Welcome to DragonFly! 
223
224
225
226  DragonFly is a 4.4BSD-Lite based operating system for Intel (x86) and amd64 (x86_64). You can also read about [the history of DragonFly](history.html), or the [ current release](history.html#RELNOTES).
227
228
229
230 ## 1.2.1 What Can DragonFly Do? 
231
232
233
234 <!-- Cutout of "features". This is outdated bullshit -->
235
236
237
238  DragonFly is based on the 4.4BSD-Lite release from Computer Systems Research Group (CSRG) at the University of California at Berkeley, along with later development of FreeBSD by the FreeBSD Project. It carries on the distinguished tradition of BSD systems development. In addition to the fine work provided by CSRG, the DragonFly Project has put in many thousands of hours in fine tuning the system for maximum performance and reliability in real-life load situations. As many of the commercial giants struggle to field PC operating systems with such features, performance and reliability, DragonFly can offer them ***now***!
239
240
241
242
243  The applications to which DragonFly can be put are truly limited only by your own imagination. From software development to factory automation, inventory control to azimuth correction of remote satellite antennae; if it can be done with a commercial UNIX product then it is more than likely that you can do it with DragonFly too! DragonFly also benefits significantly from literally thousands of high quality applications developed by research centers and universities around the world, often available at little to no cost. Commercial applications are also available and appearing in greater numbers every day.
244
245
246
247
248  Because the source code for DragonFly itself is generally available, the system can also be customized to an almost unheard of degree for special applications or projects, and in ways not generally possible with operating systems from most major commercial vendors. Here is just a sampling of some of the applications in which people are currently using DragonFly:
249
250
251
252 The robust TCP/IP networking built into DragonFly makes it an ideal platform for a variety of Internet services such as:
253
254 * FTP servers
255 * World Wide Web servers (standard or secure [SSL])
256 * Firewalls and NAT (***IP masquerading***) gateways
257 * Electronic Mail servers
258 * USENET News or Bulletin Board Systems
259 * And more...
260
261
262
263 With DragonFly, you can easily start out small with an inexpensive 386 class PC and upgrade all the way up to a quad-processor Xeon with RAID storage as your enterprise grows.
264
265
266
267 * ***Education:*** Are you a student of computer science or a related engineering field? There is no better way of learning about operating systems, computer architecture and networking than the hands on, under the hood experience that DragonFly can provide. A number of freely available CAD, mathematical and graphic design packages also make it highly useful to those whose primary interest in a computer is to get ***other*** work done!
268
269
270 * ***Research:*** With source code for the entire system available, DragonFly is an excellent platform for research in operating systems as well as other branches of computer science. DragonFly's freely available nature also makes it possible for remote groups to collaborate on ideas or shared development without having to worry about special licensing agreements or limitations on what may be discussed in open forums.
271
272
273 * ***Networking:*** Need a new router? A name server (DNS)? A firewall to keep people out of your internal network? DragonFly can easily turn that unused older PC sitting in the corner into an advanced router with sophisticated packet-filtering capabilities.
274
275
276 * ***X Window workstation:*** DragonFly is a fine choice for an inexpensive X terminal solution, either using the freely available XFree86™ or X.org servers or one of the excellent commercial servers provided by [Xi Graphics](http://www.xig.com). Unlike an X terminal, DragonFly allows many applications to be run locally if desired, thus relieving the burden on a central server. DragonFly can even boot ***diskless***, making individual workstations even cheaper and easier to administer.
277
278
279 * ***Software Development:*** The basic DragonFly system comes with a full complement of development tools including the renowned GNU C/C++ compiler and debugger.
280
281  DragonFly is available via anonymous FTP or GIT. Please see [Appendix A](mirrors.html) for more information about obtaining DragonFly.
282
283
284
285
286 ----
287
288
289
290 # About the DragonFly Project 
291
292
293
294  The following section provides some background information on the project, including a brief history, project goals, and the development model of the project.
295
296
297 ## A Brief History of DragonFly 
298
299
300
301 Matthew Dillon, one of the developers for FreeBSD, was growing increasingly frustrated with the FreeBSD Project's direction for release 5. The FreeBSD 5 release had been delayed multiple times, and had performance problems compared to earlier releases of FreeBSD.  DragonFly was announced in June of 2003. The code base was taken from the 4.8 release of FreeBSD, which offered better performance and more complete features. Development has proceeded at a very quick rate since then, with Matt Dillon and a group of developers fixing longstanding BSD bugs and modernizing the new DragonFly system.
302
303
304
305 ## DragonFly Project Goals 
306
307 DragonFly is an effort to maintain the traditional BSD format -- lean, stable code -- along with modern features such as lightweight threads, a workable packaging system, and a revised VFS. Underpinning all this work is efficient support for multiple processors, something rare among open source systems. Because DragonFly is built on an existing very stable code base, it is possible to make these radical changes as part of an incremental process.
308
309
310
311 ## The DragonFly Development Model 
312
313 ***Written by Justin Sherrill. ***
314
315 DragonFly is developed by many people around the world. There is no qualification process; anyone may submit his or her code, documentation, or designs, for use in the Project. Here is a general description of the Project's organizational structure.
316
317
318 Source for DragonFly is kept in [git](http://www.git.org/) which is available with each DragonFly install. The primary [git repository](http://gitweb.dragonflybsd.org/?p=dragonfly.git;a=summary) resides on a machine in California, USA. Documentation on obtaining the DragonFly source is available elsewhere in this book. The best way of getting changes made to the DragonFly source is to mail the [submit](http://www.dragonflybsd.org/mailinglists/) mailing list. Including desired source code changes (unified diff format is best) is the most useful format. A certain number of developers have access to commit changes to the DragonFly source, and can do so after review on that list. The DragonFly development model is loose; changes to the code are generally peer-reviewed and added when any objections have been corrected. There is no formal entry/rejection process, though final say on all code submissions goes to Matt Dillon, as originator of this project.
319
320
321
322 ## The Current DragonFly Release 
323
324 DragonFly is a freely available, full source 4.4BSD-Lite based release for almost all Intel and AMD based computer systems. It is based primarily on FreeBSD 4.8, and includes enhancements from U.C. Berkeley's CSRG group, NetBSD, OpenBSD, 386BSD, and the Free Software Foundation. A number of additional documents which you may find very helpful in the process of installing and using DragonFly may now also be found in the `/usr/share/doc` directory on any machine.
325
326
327
328 ## DragonFly Origin 
329
330
331 Matthew Dillon happened to take a picture of a dragonfly in his garden while trying to come up with a name for this new branch of BSD. Taking this as inspiration, "DragonFly" became the new name.
332
333
334
335
336
337
338 ----
339
340
341
342 ## Chapter 2 Installation from CD 
343
344 This document describes the installation of DragonFly BSD. This process uses a bootable DragonFly CD, usually referred to as a 'live CD'.  This CD is available at one of the current mirrors, which distribute the images by various protocols. The authorative list can be found at the [DragonFly website](http://www.dragonflybsd.org/download/).
345
346 <!-- XXX: add stuff about usb stick -->
347
348
349 ----
350
351
352
353 ## 2.1 First steps 
354
355
356
357 Upon booting, you see the following screen:
358
359 <!-- XXX: insert image -->
360
361
362 As you can see, it gives you the option of logging in as `root` to run the live CD and play around or logging in as `installer` to install DragonFly to your hard drive. 
363
364 Log in as `installer`. You will then see the following screen:
365
366 <!-- XXX: insert image -->
367
368
369
370 ## Set up Disk for Installation 
371
372 Note the warning to backup important data. Things can always go wrong and if, for example, you have another partition with important files, a mistype or other error might lose all the information on that partition. Assuming this is done, or that you aren't worried about other data on the machine, again, select install DragonFly BSD and you will be taken to the next screen:
373
374 <!-- XXX: insert image-->
375
376 If you have multiple disks installed, chose one where you want to install DragonFly.  We chose `ad0` here.
377
378 <!-- XXX: insert image-->
379
380 After selecting the disk we need to decide how much of the disk we want to use.  We choose to use the entire disk and see the next screen.  Now we can chose between the two file systems on DragonFly.  HAMMER is the brand-new file system with a big number of features like snapshots, history tracking, mirroring etc.  UFS is the old BSD file system.
381 <!-- XXX: mention stuf about UFS+HAMMER being the default setup, and why. -->
382
383 <!-- XXX: insert image -->
384
385 We select HAMMER and see now the following screen:
386
387 <!-- XXX: insert image -->
388
389 The screen (shown above) gives the default partition scheme for this drive. As the screen says, the * indicates that it will use remainder of the disk.  If you chose HAMMER as your file system there is no need to change the default settings.  One swap partition is created and the remaining space is assigned to the root partition.  The installer will automatically add sub-partitions (called Pseudo File Systems (PFS) in HAMMER) for /home, /usr, /var, /var/crash, /var/tmp and /tmp for you.  If you want to get more information about HAMMER, have a look in the man page.
390
391
392
393
394
395 ## Install to Disk 
396
397 The following steps show how DragonFly can be installed to your hard disk:
398
399 <!-- XXX: image -->
400
401 Depending on your hardware installing DragonFly will take some time. Once installation is complete, you are given an option to install bootblocks. Note that if you are installing bootblocks and the DragonFly installation is above the 1024th cylinder (approximately 8 gigs) accept the default of having packet mode selected:
402
403 <!-- XXX: image -->
404
405 Next, we are given an option to configure the system or reboot:
406
407 <!-- XXX: image -->
408
409
410
411
412
413 ## Set up your system 
414
415
416 The following menu of the installer allows you to configure your previously installed system.
417
418 <!-- XXX: image -->
419
420 This includes setting a password for your `root` account:
421
422 <!-- XXX: image -->
423
424 Be sure to select the correct keyboard map for your system:
425
426 <!-- XXX: image -->
427
428 Configure the hostname is done like that:
429
430 <!-- XXX: image -->
431
432 ### Add a new user 
433
434 To perform your daily work, it is recommended to work as an unprivileged user.  Use the following screen to create such an account.  If you want to allow your user to use [su(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=su&section1), also add him to the `wheel` group:
435
436 <!-- XXX: image -->
437
438 ### Configure the Network 
439
440 The next screen allows you to setup your network.  The installed card seen here is an Intel Ethernet 1000 powered by [em(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=em&section4):
441
442
443 <!-- XXX: image -->
444
445 After finishing your configuration you can escape into a live shell or reboot the system into your installation.
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460 ## Chapter 3 UNIX Basics 
461
462 ***Rewritten by Chris Shumway. ***
463
464
465
466 ## 3.1 Synopsis 
467
468
469
470 The following chapter will cover the basic commands and functionality of the DragonFly operating system. Much of this material is relevant for any UNIX®-like operating system. Feel free to skim over this chapter if you are familiar with the material. If you are new to DragonFly, then you will definitely want to read through this chapter carefully.
471
472
473
474 After reading this chapter, you will know:
475
476
477
478
479 * How to use the ***virtual consoles*** of DragonFly.
480
481
482 * How UNIX file permissions work along with understanding file flags in DragonFly.
483
484
485 * The default DragonFly file system layout.
486
487
488 * The DragonFly disk organization.
489
490
491 * How to mount and unmount file systems.
492
493
494 * What processes, daemons, and signals are.
495
496
497 * What a shell is, and how to change your default login environment.
498
499
500 * How to use basic text editors.
501
502
503 * What devices and device nodes are.
504
505
506 * What binary format is used under DragonFly.
507
508
509 * How to read manual pages for more information.
510
511
512
513
514
515
516
517 CategoryHandbook
518
519 Category
520
521 ## Virtual Consoles and Terminals 
522
523
524 DragonFly can be used in various ways. One of them is typing commands to a text terminal. A lot of the flexibility and power of a UNIX® operating system is readily available at your hands when using DragonFly this way. This section describes what ***terminals*** and ***consoles*** are, and how you can use them in !DragonFly.
525
526 <!-- XXX: also mention vesa.ko and other modes for the vt, but maybe somewhere else -->
527
528 ### The Console 
529
530 If you have not configured DragonFly to automatically start a graphical environment during startup, the system will present you with a login prompt after it boots, right after the startup scripts finish running. You will see something similar to:
531
532
533     Additional ABI support:.
534     Starting cron.
535     Local package initialization:.
536     Additional TCP options:.
537     
538     Wed Feb 18 17:53:48 GMT 2009
539     
540     DragonFly/i386 (Amnesiac) (ttyv0)
541
542     login: 
543
544
545 The messages might be a bit different on your system, but you will see something similar. The last two lines are what we are interested in right now. The second last line reads:
546
547
548     DragonFly/i386 (Amnesiac) (ttyv0)
549
550
551 This line contains some bits of information about the system you have just booted. You are looking at a ***DragonFlyBSD*** console, running on an Intel or compatible processor of the x86 architecture[(1)](#FTN.AEN1036). The name of this machine (every UNIX machine has a name) is `Amnesiac`, and you are now looking at its system console--the `ttyv0` terminal. Finally, the last line is always:
552
553
554     login:
555
556
557 This is the part where you are supposed to type in your <i>username</i> to log into DragonFly. The next section describes how you can do this.
558
559
560 ### Logging into DragonFly 
561
562 DragonFly is a multiuser, multiprocessing system. This is the formal description that is usually given to a system that can be used by many different people, who simultaneously run a lot of programs on a single machine. Every multiuser system needs some way to distinguish one <i>user</i>from the rest. In !DragonFly (and all the UNIX-like operating systems), this is accomplished by requiring that every user must ***log into*** the system before being able to run programs. Every user has a unique name (the <i>username</i> and a personal, secret key (the <i>password</i>). DragonFly will ask for these two before allowing a user to run any programs.
563
564 Right after DragonFly boots and finishes running its startup scripts[(2)](#FTN.AEN1060), it will present you with a prompt and ask for a valid username: 
565
566     login:
567
568 For the sake of this example, let us assume that your username is `john`. Type `john` at this prompt and press  **Enter** . You should then be presented with a prompt to enter a <i>password</i>:
569     
570
571     login: john
572     Password:
573
574
575
576 Type in `john`'s password now, and press  **Enter** . The password is <i>not echoed!</i> You need not worry about this right now. Suffice it to say that it is done for security reasons. If you have typed your password correctly, you should by now be logged into DragonFly and ready to try out all the available commands. You should see the MOTD or message of the day followed by a command prompt (a `#`, `$`, or `%` character). This indicates you have successfully logged into DragonFly.
577
578 ### Multiple Consoles 
579
580 Running UNIX commands in one console is fine, but DragonFly can run many programs at once. Having one console where commands can be typed would be a bit of a waste when an operating system like DragonFly can run dozens of programs at the same time. This is where <i>virtual consoles</i> can be very helpful. DragonFly can be configured to present you with many different virtual consoles. You can switch from one of them to any other virtual console by pressing a couple of keys on your keyboard. Each console has its own different output channel, and DragonFly takes care of properly redirecting keyboard input and monitor output as you switch from one virtual console to the next.
581
582
583 Special key combinations have been reserved by DragonFly for switching consoles[(3)](#FTN.AEN1087). You can use  **Alt** - **F1** ,  **Alt** - **F2** , through  **Alt** - **F8**  to switch to a different virtual console in DragonFly. As you are switching from one console to the next, DragonFly takes care of saving and restoring the screen output. The result is an <i>illusion</i> of having multiple <i>virtual</i> screens and keyboards that you can use to type commands for DragonFly to run. The programs that you launch on one virtual console do not stop running when that console is not visible. They continue running when you have switched to a different virtual console.
584
585
586 ### The /etc/ttys File 
587
588 The default configuration of DragonFly will start up with eight virtual consoles. This is not a hardwired setting though, and you can easily customize your installation to boot with more or fewer virtual consoles. The number and settings of the virtual consoles are configured in the `/etc/ttys` file.
589
590
591 You can use the `/etc/ttys` file to configure the virtual consoles of DragonFly. Each uncommented line in this file (lines that do not start with a `#` character) contains settings for a single terminal or virtual console. The default version of this file that ships with DragonFly configures nine virtual consoles, and enables eight of them. They are the lines that start with `ttyv`:
592     
593
594     # name  getty                           type    status          comments
595     #
596     ttyv0   "/usr/libexec/getty Pc"         cons25  on  secure
597     # Virtual terminals
598     ttyv1   "/usr/libexec/getty Pc"         cons25  on  secure
599     ttyv2   "/usr/libexec/getty Pc"         cons25  on  secure
600     ttyv3   "/usr/libexec/getty Pc"         cons25  on  secure
601     ttyv4   "/usr/libexec/getty Pc"         cons25  on  secure
602     ttyv5   "/usr/libexec/getty Pc"         cons25  on  secure
603     ttyv6   "/usr/libexec/getty Pc"         cons25  on  secure
604     ttyv7   "/usr/libexec/getty Pc"         cons25  on  secure
605     ttyv8   "/usr/pkg/xorg/bin/xdm -nodaemon"  xterm   off secure
606
607
608 For a detailed description of every column in this file and all the options you can use to set things up for the virtual consoles, consult the [ttys(5)](http://leaf.dragonflybsd.org/cgi/web-man?command#ttys&section5) manual page.
609
610
611
612 ### Single User Mode Console 
613
614 A detailed description of what <i>single user mode</i> is can be found in [boot-init.html#BOOT-SINGLEUSER Section 7.5.2]. It is worth noting that there is only one console when you are running DragonFly in single user mode. There are no virtual consoles available. The settings of the single user mode console can also be found in the `/etc/ttys` file. Look for the line that starts with `console`:
615
616     
617
618     # name  getty                           type    status          comments
619     #
620     # If console is marked "insecure", then init will ask for the root password
621     # when going to single-user mode.
622     console none                            unknown off secure
623
624
625
626
627
628  **Note:** As the comments above the `console` line indicate, you can edit this line and change `secure` to `insecure`. If you do that, when DragonFly boots into single user mode, it will still ask for the `root` password. ***Be careful when changing this to insecure***. If you ever forget the `root` password, booting into single user mode is a bit involved. It is still possible, but it might be a bit hard for someone who is not very comfortable with the DragonFly booting process and the programs involved.
629
630
631
632 #### Notes 
633
634
635
636 [[!table  data="""
637 <tablestyle="width:100%">[ (1)](consoles.html#AEN1036) | This is what `i386` means. Note that even if you are not running DragonFly on an Intel 386 CPU, this is going to be `i386`. It is not the type of your processor, but the processor ***architecture*** that is shown here. 
638  [ (2)](consoles.html#AEN1060) | Startup scripts are programs that are run automatically by DragonFly when booting. Their main function is to set things up for everything else to run, and start any services that you have configured to run in the background doing useful things. 
639  [ (3)](consoles.html#AEN1087) | A fairly technical and accurate description of all the details of the DragonFly console and keyboard drivers can be found in the manual pages of [syscons(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=syscons&section4), [atkbd(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=atkbd&section=4), [vidcontrol(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=vidcontrol&section=1) and [kbdcontrol(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=kbdcontrol&section=1). We will not expand on the details here, but the interested reader can always consult the manual pages for a more detailed and thorough explanation of how things work. |
640
641 """]]
642
643
644
645
646
647 CategoryHandbook
648
649 CategoryHandbook-basics
650
651
652
653 ## Permissions 
654
655 DragonFly, being a direct descendant of BSD UNIX®, is based on several key UNIX concepts. The first and most pronounced is that DragonFly is a multi-user operating system. The system can handle several users all working simultaneously on completely unrelated tasks. The system is responsible for properly sharing and managing requests for hardware devices, peripherals, memory, and CPU time fairly to each user.
656
657 Because the system is capable of supporting multiple users, everything the system manages has a set of permissions governing who can read, write, and execute the resource. These permissions are stored as three octets broken into three pieces, one for the owner of the file, one for the group that the file belongs to, and one for everyone else. This numerical representation works like this:
658
659
660
661 [[!table  data="""
662 |<tablestyle="width:100%"> Value | Permission | Directory Listing 
663 <tablestyle="width:100%"> 0 | No read, no write, no execute | `---` 
664  1 | No read, no write, execute | `--x` 
665  2 | No read, write, no execute | `-w-` 
666  3 | No read, write, execute | `-wx` 
667  4 | Read, no write, no execute | `r--` 
668  5 | Read, no write, execute | `r-x` 
669  6 | Read, write, no execute | `rw-` 
670  7 | Read, write, execute | `rwx` |
671
672 """]]
673
674 You can use the `-l` command line argument to [ls(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ls&section1) to view a long directory listing that includes a column with information about a file's permissions for the owner, group, and everyone else. For example, a `ls -l` in an arbitrary directory may show:
675
676
677
678     % ls -l
679     total 530
680     -rw-r--r--  1 root  wheel     512 Sep  5 12:31 myfile
681     -rw-r--r--  1 root  wheel     512 Sep  5 12:31 otherfile
682     -rw-r--r--  1 root  wheel    7680 Sep  5 12:31 email.txt
683     ...
684
685 Here is how the first column of `ls -l` is broken up:    
686
687     -rw-r--r--
688
689 <!-- XXX: Check all these http:// links to see if they are broken -->
690
691 The first (leftmost) character tells if this file is a regular file, a directory, a special character device, a socket, or any other special pseudo-file device. In this case, the `-` indicates a regular file. The next three characters, `rw-` in this example, give the permissions for the owner of the file. The next three characters, `r--`, give the permissions for the group that the file belongs to. The final three characters, `r--`, give the permissions for the rest of the world. A dash means that the permission is turned off. In the case of this file, the permissions are set so the owner can read and write to the file, the group can read the file, and the rest of the world can only read the file. According to the table above, the permissions for this file would be `644`, where each digit represents the three parts of the file's permission.
692
693
694
695 This is all well and good, but how does the system control permissions on devices? DragonFly actually treats most hardware devices as a file that programs can open, read, and write data to just like any other file. These special device files are stored on the `/dev` directory.
696
697
698
699 Directories are also treated as files. They have read, write, and execute permissions. The executable bit for a directory has a slightly different meaning than that of files. When a directory is marked executable, it means it can be traversed into, that is, it is possible to ***cd*** (change directory) into it. This also means that within the directory it is possible to access files whose names are known (subject, of course, to the permissions on the files themselves).
700
701 In particular, in order to perform a directory listing, read permission must be set on the directory, whilst to delete a file that one knows the name of, it is necessary to have write ***and*** execute permissions to the directory containing the file. There are more permission bits, but they are primarily used in special circumstances such as setuid binaries and sticky directories. If you want more information on file permissions and how to set them, be sure to look at the [chmod(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=chmod&section1) manual page.
702
703
704
705 ### Symbolic Permissions 
706
707
708
709 ***Contributed by Tom Rhodes.***
710
711
712
713 Symbolic permissions, sometimes referred to as symbolic expressions, use characters in place of octal values to assign permissions to files or directories. Symbolic expressions use the syntax of (who) (action) (permissions), where the following values are available:
714
715
716
717 [[!table  data="""
718 <tablestyle="width:100%"> Option | Letter | Represents 
719 <tablestyle="width:100%"> (who) | u | User 
720  (who) | g | Group owner 
721  (who) | o | Other 
722  (who) | a | All (***world***) 
723  (action) | + | Adding permissions 
724  (action) | - | Removing permissions 
725  (action) | = | Explicitly set permissions 
726  (permissions) | r | Read 
727  (permissions) | w | Write 
728  (permissions) | x | Execute 
729  (permissions) | t | Sticky bit 
730  (permissions) | s | Set UID or GID |
731
732 """]]
733
734 These values are used with the [chmod(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=chmod&amp;section1) command just like before, but with letters. For an example, you could use the following command to block other users from accessing `FILE`:
735
736
737
738     
739
740     % chmod go=FILE
741
742
743
744
745
746 A comma separated list can be provided when more than one set of changes to a file must be made. For example the following command will remove the groups and ***world*** write permission on `FILE`, then it adds the execute permissions for everyone:
747
748
749
750     
751
752     % chmod go-w,a+x FILE
753
754
755
756
757
758 ### DragonFly File Flags 
759
760
761
762 ***Contributed by Tom Rhodes.***
763
764
765
766 In addition to file permissions discussed previously, DragonFly supports the use of ***file flags.*** These flags add an additional level of security and control over files, but not directories. These file flags add an additional level of control over files, helping to ensure that in some cases not even the `root` can remove or alter files.  File flags are altered by using the [chflags(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=chflags&amp;section1) utility, using a simple interface. For example, to enable the system undeletable flag on the file `file1`, issue the following command:
767
768
769
770     
771
772     # chflags sunlink file1
773
774
775
776
777
778 And to disable the system undeletable flag, simply issue the previous command with ***no*** in front of the `sunlink`. Observe:
779
780
781
782     
783
784     # chflags nosunlink file1
785
786
787
788
789
790 To view the flags of this file, use the [ls(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ls&amp;section1) with the `-lo` flags:
791
792
793
794     
795
796     # ls -lo file1
797
798
799
800
801
802 The output should look like the following:
803
804
805
806     
807
808     -rw-r--r--  1 trhodes  trhodes  sunlnk 0 Mar  1 05:54 file1
809
810
811
812
813
814 Several flags may only added or removed to files by the `root` user. In other cases, the file owner may set these flags. It is recommended an administrator read over the [chflags(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=chflags&section1) and [chflags(2)](http://leaf.dragonflybsd.org/cgi/web-man?command=chflags&section=2) manual pages for more information.
815
816
817
818
819 ## Directory Structure 
820
821
822
823 The DragonFly directory hierarchy is fundamental to obtaining an overall understanding of the system. The most important concept to grasp is that of the root directory, ***/***. This directory is the first one mounted at boot time and it contains the base system necessary to prepare the operating system for multi-user operation. The root directory also contains mount points for every other file system that you may want to mount.
824
825
826
827 A mount point is a directory where additional file systems can be grafted onto the root file system. This is further described in [ this Section](disk-organization.html). Standard mount points include `/usr`, `/var`, `/tmp`, `/mnt`, and `/cdrom`. These directories are usually referenced to entries in the file `/etc/fstab`. `/etc/fstab` is a table of various file systems and mount points for reference by the system. Most of the file systems in `/etc/fstab` are mounted automatically at boot time from the script [rc(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rc&section8) unless they contain the `noauto` option. Details can be found in [ this section](mount-unmount.html#DISKS-FSTAB).
828
829
830
831 A complete description of the file system hierarchy is available in [hier(7)](http://leaf.dragonflybsd.org/cgi/web-man?command=hier&section7). For now, a brief overview of the most common directories will suffice.
832
833
834
835 [[!table  data="""
836 <tablestyle="width:100%">Directory | Description 
837 <tablestyle="width:100%">  `/` | Root directory of the file system. 
838  `/bin/` | User utilities fundamental to both single-user and multi-user environments. 
839  `/boot/` | Programs and configuration files used during operating system bootstrap. 
840  `/boot/defaults/` | Default bootstrapping configuration files; see [loader.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=loader.conf&section5). 
841  `/dev/` | Device nodes; see [intro(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=intro&section4). 
842  `/etc/` | System configuration files and scripts. 
843  `/etc/defaults/` | Default system configuration files; see [rc(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rc&section8). 
844  `/etc/mail/` | Configuration files for mail transport agents such as [sendmail(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=sendmail&section8). 
845  `/etc/namedb/` | `named` configuration files; see [named(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=named&section8). 
846  `/etc/periodic/` | Scripts that are run daily, weekly, and monthly, via [cron(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=cron&section8); see [periodic(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=periodic&section=8). 
847  `/etc/ppp/` | `ppp` configuration files; see [ppp(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=ppp&section8). 
848  `/mnt/` | Empty directory commonly used by system administrators as a temporary mount point. 
849  `/proc/` | Process file system; see [procfs(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=procfs&section5), [mount_procfs(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=mount_procfs&section=8). 
850  `/root/` | Home directory for the `root` account. 
851  `/sbin/` | System programs and administration utilities fundamental to both single-user and multi-user environments. 
852  `/tmp/` | Temporary files. The contents of `/tmp` are usually NOT preserved across a system reboot. A memory-based file system is often mounted at `/tmp`. This can be automated with an entry in `/etc/fstab`; see [mfs(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=mfs&section8). 
853  `/usr/` | The majority of user utilities and applications. 
854  `/usr/bin/` | Common utilities, programming tools, and applications. 
855  `/usr/include/` | Standard C include files. 
856  `/usr/lib/` | Archive libraries. 
857  `/usr/libdata/` | Miscellaneous utility data files. 
858  `/usr/libexec/` | System daemons &amp; system utilities (executed by other programs). 
859  `/usr/local/` | Local executables, libraries, etc. Within `/usr/local`, the general layout sketched out by [hier(7)](http://leaf.dragonflybsd.org/cgi/web-man?command=hier&section7) for `/usr` should be used. An exceptions is the man directory, which is directly under `/usr/local` rather than under `/usr/local/share`. 
860  `/usr/obj/` | Architecture-specific target tree produced by building the `/usr/src` tree. 
861  `/usr/pkg` | Used as the default destination for the files installed via the pkgsrc® tree or pkgsrc packages (optional). The configuration directory is tunable, but the default location is `/usr/pkg/etc`. 
862  `/usr/pkg/xorg/` | Xorg distribution executables, libraries, etc (optional). 
863  `/usr/pkgsrc` | The pkgsrc tree for installing packages (optional). 
864  `/usr/sbin/` | System daemons &amp; system utilities (executed by users). 
865  `/usr/share/` | Architecture-independent files. 
866  `/usr/src/` | BSD and/or local source files. 
867  `/var/` | Multi-purpose log, temporary, transient, and spool files. A memory-based file system is sometimes mounted at `/var`. This can be automated with an entry in `/etc/fstab`; see [mfs(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=mfs&section8). 
868  `/var/log/` | Miscellaneous system log files. 
869  `/var/mail/` | User mailbox files. 
870  `/var/spool/` | Miscellaneous printer and mail system spooling directories. 
871  `/var/tmp/` | Temporary files. The files are usually preserved across a system reboot, unless `/var` is a memory-based file system. 
872  `/var/yp` | NIS maps. |
873
874 """]]
875
876
877
878
879 ## Disk Organization 
880
881
882
883 The smallest unit of organization that DragonFly uses to find files is the filename. Filenames are case-sensitive, which means that `readme.txt` and `README.TXT` are two separate files. DragonFly does not use the extension (`.txt`) of a file to determine whether the file is a program, or a document, or some other form of data.
884
885
886
887 Files are stored in directories.  A directory may contain no files, or it may contain many hundreds of files.  A directory can also contain other directories, allowing you to build up a hierarchy of directories within one another.  This makes it much easier to organize your data.
888
889
890
891 Files and directories are referenced by giving the file or directory name, followed by a forward slash, `/`, followed by any other directory names that are necessary.  If you have directory `foo`, which contains directory `bar`, which contains the file `readme.txt`, then the full name, or ***path*** to the file is `foo/bar/readme.txt`.
892
893
894
895 Directories and files are stored in a file system. Each file system contains exactly one directory at the very top level, called the ***root directory*** for that file system.  This root directory can then contain other directories.
896
897
898
899 So far this is probably similar to any other operating system you may have used.  There are a few differences; for example, MS-DOS® and Windows® use `\`.
900
901
902 DragonFly does not use drive letters, or other drive names in the path. You would not write `c:/foo/bar/readme.txt` on DragonFly.
903
904
905
906 Instead, one file system is designated the ***root file system***.  The root file system's root directory is referred to as `/`.  Every other file system is then ***mounted*** under the root file system. No matter how many disks you have on your DragonFly system, every directory appears to be part of the same disk.
907
908
909
910 Suppose you have three file systems, called `A`, `B`, and `C`. Each file system has one root directory, which contains two other directories, called `A1`, `A2` (and likewise `B1`, `B2` and `C1`, `C2`).
911
912
913
914 Call `A` the root file system. If you used the `ls` command to view the contents of this directory you would see two subdirectories, `A1` and `A2`.  The directory tree looks like this:
915
916
917 <!-- XXX: image -->
918
919
920
921 A file system must be mounted on to a directory in another file system. So now suppose that you mount file system `B` on to the directory `A1`.  The root directory of `B` replaces `A1`, and the directories in `B` appear accordingly:
922
923
924
925 <!-- XXX: image -->
926
927
928 Any files that are in the `B1` or `B2` directories can be reached with the path `/A1/B1` or `/A1/B2` as necessary. Any files that were in `/A1` have been temporarily hidden.  They will reappear if `B` is ***unmounted*** from A.
929
930
931
932 If `B` had been mounted on `A2` then the diagram would look like this:
933
934
935 <!-- XXX: image -->
936
937
938
939 and the paths would be `/A2/B1` and `/A2/B2` respectively.
940
941
942
943 File systems can be mounted on top of one another.  Continuing the last example, the `C` file system could be mounted on top of the `B1` directory in the `B` file system, leading to this arrangement:
944
945
946 <!-- XXX: image -->
947
948
949
950 Or `C` could be mounted directly on to the `A` file system, under the `A1` directory:
951
952
953 <!-- XXX: image -->
954
955
956
957 If you are familiar with MS-DOS, this is similar, although not identical, to the `join` command.
958
959
960
961
962
963 ### Choosing File System Layout 
964
965
966
967 This is not normally something you need to concern yourself with. Typically you create file systems when installing DragonFly and decide where to mount them, and then never change them unless you add a new disk.
968
969
970
971 It is entirely possible to have one large root file system, and not need to create any others. There are some drawbacks to this approach, and one advantage.
972
973
974
975  **Benefits of Multiple File Systems** 
976
977
978
979
980 * Different file systems can have different ***mount options***.  For example, with careful planning, the root file system can be mounted read-only, making it impossible for you to inadvertently delete or edit a critical file.  Separating user-writable file systems, such as `/home`, from other file systems also allows them to be mounted ***nosuid***; this option prevents the ***suid***/***guid*** bits on executables stored on the file system from taking effect, possibly improving security.
981
982
983 * The UFS file system automatically optimizes the layout of files, depending on how the file system is being used. So a file system that contains many small files that are written frequently will have a different optimization to one that contains fewer, larger files.  By having one big file system this optimization breaks down.
984
985
986 * DragonFly's file systems are very robust should you lose power.  However, a power loss at a critical point could still damage the structure of the file system.  By splitting your data over multiple file systems it is more likely that the system will still come up, making it easier for you to restore from backup as necessary. This a major reason to make the root file system of limited size, and with low write activity.
987
988
989
990  **Benefit of a Single File System** 
991
992
993
994
995 * File systems are a fixed size. If you create a file system when you install DragonFly and give it a specific size, you may later discover that you need to make the partition bigger.  The [growfs(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=growfs&amp;section8) command makes it possible to increase the size of a UFS file system on the fly.
996 <!-- XXX: what about hammer? -->
997
998
999
1000
1001 ### Disk Slices, Partitions and local UNIX file systems 
1002
1003 Here we describe how disks are subdivided.
1004
1005 <!-- XXX: mention serno stuff -->
1006
1007 #### Slices 
1008
1009 A disk can be subdivided in slices.
1010
1011 Slices are named `s0`, `s1` and so on.
1012
1013 For example the disk `ad6` can contain the slice `ad6s3`.
1014
1015 DragonFly support two schemes for slices, MBR and GPT, either of them will manage all slices on a disk:
1016
1017
1018 * MBR: set up using [fdisk(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=fdisk&amp;section8), can be up to 2 TB in size.  MBR slices are numbered from 1; but if disk is ***dangerously dedicated*** it has slice number 0.
1019
1020
1021 * GPT: set up using [gpt(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=gpt&amp;section8), can be extremely large: size up to 8 billion TB.  DragonFly doesn't support booting from a GPT slice in DragonFly  2.0.  Note that GPT slices are numbered from 0. ***Dangerously dedicated*** is not supported nor needed for GPT.  DragonFly 2.1 does have some support for booting from a GPT slice, this is described in [gpt(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=gpt&amp;section=8).
1022
1023
1024
1025 #### Partitions 
1026
1027 Partitions are contained in slices.
1028
1029 Partitions are named `a`, `b` and so on.
1030
1031 DragonFly support 16 partitions per slice, that is `a` through `p`.
1032
1033 For example the partition `ad6s3a` is contained in the slice `ad6s3`.
1034
1035 Partition layout is defined in a label on the slice where the partition reside. DragonFly support two types of disk labels, disklabel32 and disklabel64 (the default):
1036
1037
1038 * [disklabel32(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel&amp;section8): 32 bit disk label which can use slices with size up to 2 TB.
1039
1040
1041 * [disklabel64(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel64&amp;section8): 64 bit disk label which can use very large slices: size up to 16 million TB.
1042
1043
1044 #### Local UNIX file systems 
1045
1046 File systems are contained in partitions.  Each partition can contain only one file system, which means that file systems often are described by either their typical mount point in the file system hierarchy, or the letter of the partition they are contained in.  ***Partition*** does not have the same meaning as the common usage of the term partition (for example, MS-DOS partition), because of DragonFly's UNIX® heritage.
1047
1048
1049
1050 DragonFly support two local UNIX file systems, UFS and HAMMER:
1051
1052
1053 * UFS: The classical BSD UNIX file system, see [ffs(5)](http://leaf.dragonflybsd.org/cgi/web-man?command#ffs&amp;section5), it supports size up to 2 TB.
1054
1055
1056 * [HAMMER(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=HAMMER&amp;section5): A new file system, as of DragonFly 2.0, with many advanced features.  HAMMER file system support size up to 1 million TB.
1057
1058
1059
1060 #### Typical disk layout 
1061
1062 From the above we see the following typical disk layout scenarios:
1063
1064
1065 * For booting DragonFly from a local file system UFS is recommended.  A BOOT+HAMMER setup is recommended for HAMMER use, this consists of a small UFS file system for booting, typically 512MB, and a HAMMER root file system.  The BOOT file system is mounted as /boot after boot.
1066
1067
1068 * For moderate storage requirements UFS can be used; it can be setup on any partition, e.g. on the same disk slice as the boot partition.  HAMMER is an alternative, with extra features supported, like history retention.  You should evaluate if HAMMER is suitable, see note below.
1069
1070
1071 * If really big storage capacity is needed UFS can't fit the need.  You should evaluate if HAMMER is suitable, see note below.  For this use HAMMER needs to be used on a GPT slice with  a [disklabel64(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel64&amp;section8) label.  In DragonFly 2.0 it has to be set up on a disk separate from the boot disk.  In  DragonFly 2.1 one disk can be used for both booting and HAMMER file system on GPT slice, as some support for booting from GPT is present, as described in [gpt(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=gpt&amp;section=8).
1072
1073
1074
1075
1076
1077 #### HAMMER Note 
1078
1079 [HAMMER(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=HAMMER&amp;section5)
1080
1081 is a rather new file system, under active development.
1082
1083 As of DragonFly 2.2.1 release HAMMER is considered production ready.  At 2.0 release it was considered to be in an early Beta state .
1084
1085 All major features except the mirroring are quite well tested as-of the 2.2.1 release.
1086
1087 You should evaluate if HAMMER is suitable for your needs.
1088 <!-- XXX: mention disk and memory requirements for efficient hammer use -->
1089
1090
1091 Examples of ongoing development includes:
1092
1093
1094 * Making HAMMER more self managing; e.g. ability to setup policy for which history to save for how long: e.g. make snapshot every hour and prune and reblock the file system regularly.  When snapshot gets older than 1 month only keep them for every 6 hours; when older than 3 months only keep snapshot for every 24 hours, when older than 3 years only keep snapshot per month.  For now you need to set up [cron(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=cron&amp;section8) jobs for this yourself, see [hammer(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=hammer&amp;section=8).
1095
1096
1097 * Multi master mirroring. For now only one mirror master is supported, but multiple mirror targets, called slaves, are already supported.
1098
1099
1100 * Support for shrinking existing HAMMER file systems.  The HAMMER design is prepared for this, utility just have to be written to support it.
1101 <!-- XXX: is this still accurate? Do we really want to mention it here? -->
1102
1103
1104 #### HAMMER Features 
1105
1106 [HAMMER(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=HAMMER&amp;section5) has several advanced features not found in UFS:
1107
1108
1109 * Large file systems:  Up to 1 million TB, also called 1 Exabyte is supported.
1110
1111
1112 * Multiple volumes:  A HAMMER file system can span up to 256 disks, each partition part of a HAMMER file system is called a volume.  Each volume can be up to 4096 TB in size.
1113
1114
1115 * Support for growing and shrinking existing HAMMER file systems: adding and removing volumes from the file system.  As of 2.4 release an existing HAMMER file system can be expanded by adding extra space, see the `expand` directive to [hammer(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=hammer&amp;section=8).  The HAMMER design is also prepared for removing volumes, utilities just have to be written to support it.
1116
1117
1118 * Instant crash recovery:  If a crash should occur, then HAMMER file systems will be ready a few seconds after boot, no lenghty fsck have to be run.
1119
1120
1121 * Full history retention:  All file system changes are saved every ~30 seconds.  Changes are written at least when sync() is called, see [syncer(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=syncer&amp;section4).  Every time data for files are written to disk a transaction is completed, this is assigned an ID and the file updated can after this be accessed with the contents from this moment.  To access the file with the state of this moment, the transaction ID, TID for brevity, just needs to be added to the file name, like: 'file@@<TID>'.  The TID can be saved from the 'snapshot', 'cleanup', or 'synctid' [hammer(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=hammer&amp;section=8) command or looked up with the 'hammer history file' command.  This history will typically grow over time, so any disk will fill up over time.  Two things are done so disks doesn't fill up: first: big disks are used, at least 50GB is typical for HAMMER file systems, and second: unused history information is deleted regularly. Here we need to define what unused means: a TID is used if a snapshot have been taken on it. Data assigned to unused history can be reclaimed using the `prune` and `reblock` [hammer(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=hammer&amp;section=8) commands, this will also defragment the file system and can be done while the file system is in normal operation.  Generally after file system is pruned only TIDs for the snapshots or newer than newest shapshot should be used, see explanation [here](http://leaf.dragonflybsd.org/mailarchive/bugs/2008-07/msg00213.html) (more info on HAMMER design [here](http://leaf.dragonflybsd.org/mailarchive/kernel/2008-07/msg00114.html)).  See also [hammer(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=hammer&amp;section=5). 
1122
1123
1124 * Mirroring:  A master file system can be mirrored online to a number of slave file systems.  Mirror targets are read-only, but does have history available.  History retension policy can even be different on slaves and master.  Mirroring can be over network and unreliable connections are handled gracefully.
1125
1126
1127 * Data integrity:  HAMMER has high focus in data integrity and implements a CRC checksum on all data, this means that if disk fails with bit errors it will be detected.
1128
1129
1130
1131 More info on HAMMER can be found [here](http://www.dragonflybsd.org/hammer/index.shtml).
1132
1133
1134
1135 DragonFly also uses disk space for ***swap space***.  Swap space provides DragonFly with ***virtual memory***.  This allows your computer to behave as though it has much more memory than it actually does.  When DragonFly runs low on memory it moves some of the data that is not currently being used to the swap space, and moves it back in (moving something else out) when it needs it.
1136
1137 <!-- XXX: mention swapcache, and also how to configure and use it (somewhere else, probably) -->
1138
1139
1140
1141 ### Adding a Disk 
1142
1143
1144
1145 Adding a disk is done by installing it physically, and to connect it to a disk controller that DragonFly supports.  If you are in doubt if controller is supported, manual pages for disk controllers can be consulted ('man -k disk' or 'man -k scsi' can be of help).  The easiest thing is normally to boot DargonFly with the controller installed and note if boot message contains the controller.
1146
1147
1148
1149 Assuming that disk `ad6` is installed, we could set it up using [fdisk(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=fdisk&amp;section8) and  disklabel(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel&amp;section8) or  [gpt(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=gpt&amp;section8) and 
1150 [disklabel64(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel64&amp;section8).
1151
1152 In this example we choose [gpt(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=gpt&amp;section=8) & [disklabel64(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel64&amp;section=8).
1153
1154
1155 <!-- XXX: mention that disklabel64 is default now -->
1156     
1157
1158     # gpt -v create ad6
1159
1160     ...
1161
1162     # gpt add -s1 ad6
1163
1164     ad6s0
1165
1166     # gpt add ad6
1167
1168     ad6s1
1169
1170     # gpt show ad6
1171
1172     ...
1173
1174
1175
1176
1177
1178 Here we first create the GPT and then add two slices.  In this example the first slice added is `ad6s0`, which is made a dummy slice of size 1 sector, this is just for not having to make further reference to it, as many users remembers that `s0` has special meaning, which really isn't true for GPT slices.  The second slice is `ad6s1` which will cover the rest of the disk.
1179
1180
1181
1182     
1183
1184     # disklabel64 -rw ad6s1 auto
1185
1186     # disklabel64 -e ad6s1          # edit label to add partitions as needed
1187
1188
1189
1190
1191
1192 ### disklabel 
1193 <!-- XXX: what is all this fuzz about dangerously dedicated? -->
1194
1195
1196 For [disklabel(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel&amp;section8) labels some partitions have certain conventions associated with them.
1197
1198
1199
1200 [[!table  data="""
1201 <tablestyle="width:100%"> Partition | Convention 
1202 <tablestyle="width:100%"> `a` | Normally contains the root file system 
1203  `b` | Normally contains swap space 
1204  `c` | Normally the same size as the enclosing slice.  This allows utilities that need to work on the entire slice (for example, a bad block scanner) to work on the `c` partition. You would not normally create a file system on this partition. This is not necessarily true; it is possible to use the 'c' partition as a normal partition.
1205  `d` | Partition `d` used to have a special meaning associated with it, although that is now gone.  To this day, some tools may operate oddly if told to work on partition `d`. |
1206
1207 """]]
1208
1209 Each partition-that-contains-a-file-system is stored in what DragonFly calls a ***slice***.  Slice is DragonFly's term for what the common call partitions, and again, this is because of DragonFly's UNIX background.  Slices are numbered, starting at 1.
1210
1211
1212
1213 Slice numbers follow the device name, prefixed with an `s`, starting at 1. So ***da0s1*** is the first slice on the first SCSI drive. There can only be four physical slices on a disk, but you can have logical slices inside physical slices of the appropriate type.  These extended slices are numbered starting at 5, so ***ad0s5*** is the first extended slice on the first IDE disk. These devices are used by file systems that expect to occupy a slice.
1214
1215 <!-- XXX: gpt allows for way more than 4 partitions... let's remove this stuff above -->
1216
1217 ***Dangerously dedicated*** physical drives are accessed as slice 0.
1218
1219
1220
1221 Slices, ***dangerously dedicated*** physical drives, and other drives contain ***partitions***, which are represented as letters from `a` to `p`.  This letter is appended to the device name, so ***da0s0a*** is the a partition on the first da drive, which is ***dangerously dedicated***. ***ad1s3e*** is the fifth partition in the third slice of the second IDE disk drive.
1222
1223
1224
1225 Finally, each disk on the system is identified.  A disk name starts with a code that indicates the type of disk, and then a number, indicating which disk it is.  Disk numbering starts at 0. Common codes that you will see are listed in [Table 3-1](disk-organization.html#BASICS-DEV-CODES).
1226
1227 <!-- XXX: here would probably be the right place to talk about serno -->
1228
1229 When referring to a partition DragonFly requires that you also name the slice and disk that contains the partition, and when referring to a slice you should also refer to the disk name. Do this by listing the disk name, `s`, the slice number, and then the partition letter.  Examples are shown in [Example 3-1](disk-organization.html#BASICS-DISK-SLICE-PART).
1230
1231 <!-- XXX: later talk also about devfs, definitely not here though. also, devfs rules -->
1232
1233 [Example 3-2](disk-organization.html#BASICS-CONCEPT-DISK-MODEL) shows a conceptual model of the disk layout that should help make things clearer.
1234
1235
1236
1237 In order to install DragonFly you must first configure the disk slices, then create partitions within the slice you will use for DragonFly, and then create a file system (or swap space) in each partition, and decide where that file system will be mounted.
1238
1239
1240
1241 ***'Table 3-1. Disk Device Codes***'
1242
1243
1244
1245 [[!table  data="""
1246 <tablestyle="width:100%"> Code | Meaning 
1247 <tablestyle="width:100%"> `ad` | ATAPI (IDE) disk 
1248  `da` | SCSI direct access disk 
1249  `acd` | ATAPI (IDE) CDROM 
1250  `cd` | SCSI CDROM 
1251  `vn` | Virtual disk
1252  `fd` | Floppy disk |
1253
1254 """]]
1255
1256 ***'Example 3-1. Sample Disk, Slice, and Partition Names***'
1257
1258
1259
1260 [[!table  data="""
1261 <tablestyle="width:100%"> Name | Meaning 
1262 <tablestyle="width:100%"> `ad0s1a` | The first partition (`a`) on the first slice (`s1`) on the first IDE disk (`ad0`). 
1263  `da1s2e` | The fifth partition (`e`) on the second slice (`s2`) on the second SCSI disk (`da1`). |
1264
1265 """]]
1266
1267 ***'Example 3-2. Conceptual Model of a Disk***'
1268
1269
1270
1271 This diagram shows DragonFly's view of the first IDE disk attached to the system. Assume that the disk is 4 GB in size, and contains two 2 GB slices (MS-DOS partitions).  The first slice contains a MS-DOS disk, `C:`, and the second slice contains a DragonFly installation. This example DragonFly installation has three partitions, and a swap partition.
1272
1273
1274
1275 The three partitions will each hold a file system. Partition `a` will be used for the root file system, `e` for the `/var` directory hierarchy, and `f` for the `/usr` directory hierarchy.
1276
1277
1278 <!-- XXX: image -->
1279
1280
1281
1282
1283
1284
1285 CategoryHandbook
1286
1287 CategoryHandbook-basics
1288
1289
1290
1291
1292
1293
1294
1295 ## Mounting and Unmounting File Systems 
1296
1297
1298
1299 The file system is best visualized as a tree, rooted at `/`.
1300
1301 The directories, e.g. `/dev` and `/usr`, in the root directory are branches,
1302
1303 which may have their own branches, such as `/usr/local`, and so on.
1304
1305
1306
1307 There are various reasons to house some of these directories on separate file systems. `/var` contains the directories `log/` and `spool/`, and various types of temporary files, and as such, may get filled up. Filling up the root file system is not a good idea, so splitting `/var` from `/` is often favorable.
1308
1309
1310
1311 Another common reason to contain certain directory trees on other file systems is if they are to be housed on separate physical disks, e.g. CD-ROM, or are used as separate virtual disks, such as [Network File System](network-nfs.html) exports.
1312
1313
1314
1315
1316
1317 ### The fstab File 
1318
1319
1320
1321 During the [boot process](boot.html), file systems listed in `/etc/fstab` are automatically mounted (unless they are listed with the `noauto` option).
1322
1323
1324
1325 The `/etc/fstab` file contains a list of lines of the following format:
1326   
1327
1328     device       mount-point   fstype     options      dumpfreq     passno
1329
1330 These parameters have the following meaning:
1331
1332 * `device`: A device name (which should exist), as explained [here](disks-naming.html).
1333
1334 * `mount-point`: A directory (which should exist), on which to mount the file system.
1335
1336 * `fstype`: The file system type to pass to [mount(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=mount&section8). The default DragonFly file system is `ufs`.
1337
1338 * `options`: Either `rw` for read-write file systems, or `ro` for read-only file systems, followed by any other options that may be needed. A common option is `noauto` for file systems not normally mounted during the boot sequence. Other options are listed in the [mount(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=mount&section8) manual page.
1339
1340 * `dumpfreq`: This is used by [dump(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=dump&section8) to determine which file systems require dumping. If the field is missing, a value of zero is assumed.
1341
1342 * `passno`: This determines the order in which file systems should be checked. File systems that should be skipped should have their `passno` set to zero. The root file system (which needs to be checked before everything else) should have its `passno` set to one, and other file systems' `passno` should be set to values greater than one. If more than one file systems have the same `passno` then [fsck(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=fsck&section8) will attempt to check file systems in parallel if possible.
1343
1344
1345 Consult the [fstab(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=fstab&section5) manual page for more information on the format of the `/etc/fstab` file and the options it contains.
1346
1347
1348
1349
1350
1351 ### The mount Command 
1352
1353
1354
1355 The [mount(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=mount&section8) command is what is ultimately used to mount file systems.
1356
1357
1358
1359 In its most basic form, you use:
1360
1361
1362
1363     
1364
1365     # mount device mountpoint
1366
1367
1368
1369
1370
1371 Or, if `mountpoint` is specified in `/etc/fstab`, just:
1372
1373
1374
1375     
1376
1377     # mount mountpoint
1378
1379
1380
1381
1382
1383 There are plenty of options, as mentioned in the [mount(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=mount&section8) manual page, but the most common are:
1384
1385
1386
1387  **Mount Options** 
1388
1389
1390
1391
1392 * `-a`: Mount all the file systems listed in `/etc/fstab`. Except those marked as `noauto`, excluded by the `-t` flag, or those that are already mounted.
1393
1394
1395 * `-d`: Do everything except for the actual mount system call. This option is useful in conjunction with the `-v` flag to determine what [mount(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=mount&section8) is actually trying to do.
1396
1397
1398 * `-f`: Force the mount of an unclean file system (dangerous), or forces the revocation of write access when downgrading a file system's mount status from read-write to read-only.
1399
1400
1401 * `-r`: Mount the file system read-only. This is identical to using the `rdonly` argument to the `-o` option.
1402
1403
1404 * `-t` ***fstype***: Mount the given file system as the given file system type, or, if used with `-a` option, mount only file systems of the given type. `ufs` is the default file system type.
1405
1406
1407 * `-u`: Update mount options on the file system.
1408
1409
1410 * `-v`: Be verbose.
1411
1412
1413 * `-w`: Mount the file system read-write.
1414
1415
1416
1417 The `-o` option takes a comma-separated list of the options, including the following:
1418
1419
1420
1421
1422 * `nodev:` Do not interpret special devices on the file system. This is a useful security option.
1423
1424
1425 * `noexec`: Do not allow execution of binaries on this file system. This is also a useful security option.
1426
1427
1428 * `nosuid`: Do not interpret setuid or setgid flags on the file system. This is also a useful security option.
1429
1430
1431
1432 ### The umount Command 
1433
1434
1435
1436 The [umount(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=umount&section8) command takes, as a parameter, one of a mountpoint, a device name, or the `-a` or `-A` option.
1437
1438
1439
1440 All forms take `-f` to force unmounting, and `-v` for verbosity. Be warned that `-f` is not generally a good idea. Forcibly unmounting file systems might crash the computer or damage data on the file system.
1441
1442
1443
1444 `-a` and `-A` are used to unmount all mounted file systems, possibly modified by the file system types listed after `-t`. `-A`, however, does not attempt to unmount the root file system.
1445
1446
1447
1448
1449
1450
1451
1452 CategoryHandbook
1453
1454 CategoryHandbook-basics
1455
1456
1457
1458
1459
1460
1461 ## Processes 
1462
1463
1464
1465 DragonFly is a multi-tasking operating system. This means that it seems as though more than one program is running at once. Each program running at any one time is called a ***process***. Every command you run will start at least one new process, and there are a number of system processes that run all the time, keeping the system functional.
1466
1467 <!-- XXX: talk about LWPs and threads? -->
1468
1469 Each process is uniquely identified by a number called a ***process ID***, or ***PID***, and, like files, each process also has one owner and group. The owner and group information is used to determine what files and devices the process can open, using the file permissions discussed earlier. Most processes also have a parent process. The parent process is the process that started them. For example, if you are typing commands to the shell then the shell is a process, and any commands you run are also processes. Each process you run in this way will have your shell as its parent process. The exception to this is a special process called [init(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=init&section8). `init` is always the first process, so its PID is always 1. `init` is started automatically by the kernel when DragonFly starts.
1470
1471 Two commands are particularly useful to see the processes on the system, [ps(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ps&section1) and [top(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=top&section=1). The `ps` command is used to show a static list of the currently running processes, and can show their PID, how much memory they are using, the command line they were started with, and so on. The `top` command displays all the running processes, and updates the display every few seconds, so that you can interactively see what your computer is doing.
1472
1473
1474
1475 By default, `ps` only shows you the commands that are running and are owned by you. For example:
1476
1477
1478
1479     
1480
1481     % ps
1482
1483       PID  TT  STAT      TIME COMMAND
1484       298  p0  Ss     0:01.10 tcsh
1485      7078  p0  S      2:40.88 xemacs mdoc.xsl (xemacs-21.1.14)
1486     37393  p0  I      0:03.11 xemacs freebsd.dsl (xemacs-21.1.14)
1487     48630  p0  S      2:50.89 /usr/local/lib/netscape-linux/navigator-linux-4.77.bi
1488     48730  p0  IW     0:00.00 (dns helper) (navigator-linux-)
1489     72210  p0  R+     0:00.00 ps
1490       390  p1  Is     0:01.14 tcsh
1491      7059  p2  Is+    1:36.18 /usr/local/bin/mutt -y
1492      6688  p3  IWs    0:00.00 tcsh
1493     10735  p4  IWs    0:00.00 tcsh
1494     20256  p5  IWs    0:00.00 tcsh
1495       262  v0  IWs    0:00.00 -tcsh (tcsh)
1496       270  v0  IW+    0:00.00 /bin/sh /usr/X11R6/bin/startx -- -bpp 16
1497       280  v0  IW+    0:00.00 xinit /home/nik/.xinitrc -- -bpp 16
1498       284  v0  IW     0:00.00 /bin/sh /home/nik/.xinitrc
1499       285  v0  S      0:38.45 /usr/X11R6/bin/sawfish
1500
1501
1502
1503 As you can see in this example, the output from [ps(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ps&section1) is organized into a number of columns. `PID` is the process ID discussed earlier. PIDs are assigned starting from 1, go up to 99999, and wrap around back to the beginning when you run out. The `TT` column shows the tty the program is running on, and can safely be ignored for the moment. `STAT` shows the program's state, and again, can be safely ignored. `TIME` is the amount of time the program has been running on the CPU--this is usually not the elapsed time since you started the program, as most programs spend a lot of time waiting for things to happen before they need to spend time on the CPU. Finally, `COMMAND` is the command line that was used to run the program.
1504
1505
1506
1507 [ps(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ps&section1) supports a number of different options to change the information that is displayed. One of the most useful sets is `auxww`. `a` displays information about all the running processes, not just your own. `u` displays the username of the process' owner, as well as memory usage. `x` displays information about daemon processes, and `ww` causes [ps(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ps&section=1) to display the full command line, rather than truncating it once it gets too long to fit on the screen.
1508
1509
1510
1511 The output from [top(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=top&section1) is similar. A sample session looks like this:
1512
1513
1514
1515     
1516
1517     % top
1518     last pid: 72257;  load averages:  0.13,  0.09,  0.03    up 0+13:38:33  22:39:10
1519     47 processes:  1 running, 46 sleeping
1520     CPU states: 12.6% user,  0.0% nice,  7.8% system,  0.0% interrupt, 79.7% idle
1521     Mem: 36M Active, 5256K Inact, 13M Wired, 6312K Cache, 15M Buf, 408K Free
1522     Swap: 256M Total, 38M Used, 217M Free, 15% Inuse
1523     
1524
1525       PID USERNAME PRI NICE  SIZE    RES STATE    TIME   WCPU    CPU COMMAND
1526     72257 nik       28   0  1960K  1044K RUN      0:00 14.86%  1.42% top
1527      7078 nik        2   0 15280K 10960K select   2:54  0.88%  0.88% xemacs-21.1.14
1528       281 nik        2   0 18636K  7112K select   5:36  0.73%  0.73% XF86_SVGA
1529       296 nik        2   0  3240K  1644K select   0:12  0.05%  0.05% xterm
1530     48630 nik        2   0 29816K  9148K select   3:18  0.00%  0.00% navigator-linu
1531       175 root       2   0   924K   252K select   1:41  0.00%  0.00% syslogd
1532      7059 nik        2   0  7260K  4644K poll     1:38  0.00%  0.00% mutt
1533     ...
1534
1535 The output is split into two sections. The header (the first five lines) shows the PID of the last process to run, the system load averages (which are a measure of how busy the system is), the system uptime (time since the last reboot) and the current time. The other figures in the header relate to how many processes are running (47 in this case), how much memory and swap space has been taken up, and how much time the system is spending in different CPU states.
1536
1537 Below that are a series of columns containing similar information to the output from [ps(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ps&section1). As before you can see the PID, the username, the amount of CPU time taken, and the command that was run. [top(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=top&section=1) also defaults to showing you the amount of memory space taken by the process. This is split into two columns, one for total size, and one for resident size--total size is how much memory the application has needed, and the resident size is how much it is actually using at the moment. In this example you can see that  **Netscape®**  has required almost 30 MB of RAM, but is currently only using 9 MB.
1538
1539
1540
1541 [top(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=top&section1) automatically updates this display every two seconds; this can be changed with the `s` option.
1542
1543
1544
1545
1546
1547 ## Daemons, Signals, and Killing Processes 
1548
1549
1550
1551 When you run an editor it is easy to control the editor, tell it to load files, and so on. You can do this because the editor provides facilities to do so, and because the editor is attached to a ***terminal***. Some programs are not designed to be run with continuous user input, and so they disconnect from the terminal at the first opportunity. For example, a web server spends all day responding to web requests, it normally does not need any input from you. Programs that transport email from site to site are another example of this class of application.
1552
1553
1554
1555 We call these programs ***daemons***. Daemons were characters in Greek mythology; neither good or evil, they were little attendant spirits that, by and large, did useful things for mankind. Much like the web servers and mail servers of today do useful things. This is why the mascot for a number of BSD-based operating systems has, for a long time, been a cheerful looking daemon with sneakers and a pitchfork.
1556
1557
1558
1559 There is a convention to name programs that normally run as daemons with a trailing ***d***.  **BIND**  is the Berkeley Internet Name Daemon (and the actual program that executes is called `named`), the  **Apache**  web server program is called `httpd`, the line printer spooling daemon is `lpd` and so on. This is a convention, not a hard and fast rule; for example, the main mail daemon for the  **Sendmail**  application is called `sendmail`, and not `maild`, as you might imagine.
1560
1561
1562
1563 Sometimes you will need to communicate with a daemon process. These communications are called ***signals***, and you can communicate with a daemon (or with any other running process) by sending it a signal. There are a number of different signals that you can send--some of them have a specific meaning, others are interpreted by the application, and the application's documentation will tell you how that application interprets signals. You can only send a signal to a process that you own. If you send a signal to someone else's process with [kill(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=kill&section=1) or [kill(2)](http://leaf.dragonflybsd.org/cgi/web-man?command=kill&section=2) permission will be denied. The exception to this is the `root` user, who can send signals to everyone's processes.
1564
1565
1566
1567 DragonFly will also send applications signals in some cases. If an application is badly written, and tries to access memory that it is not supposed to, DragonFly sends the process the ***Segmentation Violation*** signal (`SIGSEGV`). If an application has used the [alarm(3)](http://leaf.dragonflybsd.org/cgi/web-man?command=alarm&section=3) system call to be alerted after a period of time has elapsed then it will be sent the Alarm signal (`SIGALRM`), and so on.
1568
1569
1570
1571 Two signals can be used to stop a process, `SIGTERM` and `SIGKILL`. `SIGTERM` is the polite way to kill a process; the process can ***catch*** the signal, realize that you want it to shut down, close any log files it may have open, and generally finish whatever it is doing at the time before shutting down. In some cases a process may even ignore `SIGTERM` if it is in the middle of some task that can not be interrupted.
1572
1573
1574
1575 `SIGKILL` can not be ignored by a process. This is the ***I do not care what you are doing, stop right now*** signal. If you send `SIGKILL` to a process then DragonFly will stop that process there and then[(1)](#FTN.AEN2181).
1576
1577
1578
1579 The other signals you might want to use are `SIGHUP`, `SIGUSR1`, and `SIGUSR2`. These are general purpose signals, and different applications will do different things when they are sent.
1580
1581
1582
1583 Suppose that you have changed your web server's configuration file--you would like to tell the web server to re-read its configuration. You could stop and restart `httpd`, but this would result in a brief outage period on your web server, which may be undesirable. Most daemons are written to respond to the `SIGHUP` signal by re-reading their configuration file. So instead of killing and restarting `httpd` you would send it the `SIGHUP` signal. Because there is no standard way to respond to these signals, different daemons will have different behavior, so be sure and read the documentation for the daemon in question.
1584
1585
1586
1587 Signals are sent using the [kill(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=kill&section=1) command, as this example shows.
1588
1589
1590
1591  **Sending a Signal to a Process** 
1592
1593
1594
1595 This example shows how to send a signal to [inetd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=inetd&section=8). The `inetd` configuration file is `/etc/inetd.conf`, and `inetd` will re-read this configuration file when it is sent `SIGHUP`.
1596
1597
1598
1599   1. Find the process ID of the process you want to send the signal to. Do this using [ps(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ps&section=1) and [grep(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=grep&section=1). The [grep(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=grep&section=1) command is used to search through output, looking for the string you specify. This command is run as a normal user, and [inetd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=inetd&section=8) is run as `root`, so the `ax` options must be given to [ps(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ps&section=1).
1600
1601       
1602
1603         % ps -ax | grep inetd
1604
1605         198  ??  IWs    0:00.00 inetd -wW
1606
1607   
1608
1609   So the [inetd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#inetd&section8) PID is 198. In some cases the `grep inetd` command might also occur in this output. This is because of the way [ps(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ps&section=1) has to find the list of running processes.
1610
1611   2. Use [kill(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=kill&section=1) to send the signal. Because [inetd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=inetd&section=8) is being run by `root` you must use [su(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=su&section=1) to become `root` first.
1612
1613       
1614
1615         % su
1616
1617         Password:
1618
1619         # /bin/kill -s HUP 198
1620
1621   
1622
1623   In common with most UNIX® commands, [kill(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=kill&section=1) will not print any output if it is successful. If you send a signal to a process that you do not own then you will see `kill: PID: Operation not permitted`. If you mistype the PID you will either send the signal to the wrong process, which could be bad, or, if you are lucky, you will have sent the signal to a PID that is not currently in use, and you will see `kill: PID: No such process`.
1624
1625
1626
1627 **Why Use `/bin/kill`?** Many shells provide the `kill` command as a built in command; that is, the shell will send the signal directly, rather than running `/bin/kill`. This can be very useful, but different shells have a different syntax for specifying the name of the signal to send. Rather than try to learn all of them, it can be simpler just to use the `/bin/kill ...` command directly.
1628
1629
1630
1631 Sending other signals is very similar, just substitute `TERM` or `KILL` in the command line as necessary.
1632
1633
1634
1635  **Important:** Killing random process on the system can be a bad idea. In particular, [init(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=init&section=8), process ID 1, is very special. Running `/bin/kill -s KILL 1` is a quick way to shutdown your system. ***Always*** double check the arguments you run [kill(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=kill&section=1) with ***before*** you press  **Return** .
1636
1637  
1638  
1639  
1640  
1641  
1642 ## Shells 
1643
1644
1645
1646 In DragonFly, a lot of everyday work is done in a command line interface called a shell. A shell's main job is to take commands from the input channel and execute them. A lot of shells also have built in functions to help everyday tasks such as file management, file globbing, command line editing, command macros, and environment variables. DragonFly comes with a set of shells, such as `sh`, the Bourne Shell, and `tcsh`, the improved C-shell. Many other shells are available from pkgsrc®, such as `zsh` and `bash`.
1647
1648
1649
1650 Which shell do you use? It is really a matter of taste. If you are a C programmer you might feel more comfortable with a C-like shell such as `tcsh`. If you have come from Linux or are new to a UNIX® command line interface you might try `bash`. The point is that each shell has unique properties that may or may not work with your preferred working environment, and that you have a choice of what shell to use.
1651
1652
1653
1654 One common feature in a shell is filename completion. Given the typing of the first few letters of a command or filename, you can usually have the shell automatically complete the rest of the command or filename by hitting the  **Tab**  key on the keyboard. Here is an example. Suppose you have two files called `foobar` and `foo.bar`. You want to delete `foo.bar`. So what you would type on the keyboard is: `rm fo[ **Tab** ].[ **Tab** ]`.
1655
1656
1657
1658 The shell would print out `rm foo[BEEP].bar`.
1659
1660
1661
1662 The [BEEP] is the console bell, which is the shell telling me it was unable to totally complete the filename because there is more than one match. Both `foobar` and `foo.bar` start with `fo`, but it was able to complete to `foo`. If you type in `.`, then hit  **Tab**  again, the shell would be able to fill in the rest of the filename for you.
1663
1664
1665
1666 Another feature of the shell is the use of environment variables. Environment variables are a variable key pair stored in the shell's environment space. This space can be read by any program invoked by the shell, and thus contains a lot of program configuration. Here is a list of common environment variables and what they mean:
1667
1668
1669
1670 [[!table  data="""
1671 <tablestyle="width:100%"> Variable | Description 
1672 <tablestyle="width:100%"> `USER` | Current logged in user's name. 
1673  `PATH` | Colon separated list of directories to search for binaries. 
1674  `DISPLAY` | Network name of the X11 display to connect to, if available. 
1675  `SHELL` | The current shell. 
1676  `TERM` | The name of the user's terminal. Used to determine the capabilities of the terminal. 
1677  `TERMCAP` | Database entry of the terminal escape codes to perform various terminal functions. 
1678  `OSTYPE` | Type of operating system. e.g., DragonFly. 
1679  `MACHTYPE` | The CPU architecture that the system is running on. 
1680  `EDITOR` | The user's preferred text editor. 
1681  `PAGER` | The user's preferred text pager. 
1682  `MANPATH` | Colon separated list of directories to search for manual pages. |
1683
1684 """]]
1685
1686 Setting an environment variable differs somewhat from shell to shell. For example, in the C-Style shells such as `tcsh` and `csh`, you would use `setenv` to set environment variables. Under Bourne shells such as `sh` and `bash`, you would use `export` to set your current environment variables. For example, to set or modify the `EDITOR` environment variable, under `csh` or `tcsh` a command like this would set `EDITOR` to `/usr/pkg/bin/emacs`:
1687     
1688
1689     % setenv EDITOR /usr/pkg/bin/emacs
1690
1691
1692 Under Bourne shells:
1693    
1694
1695     % export EDITOR="/usr/pkg/bin/emacs"
1696
1697
1698
1699 You can also make most shells expand the environment variable by placing a `$` character in front of it on the command line. For example, `echo $TERM` would print out whatever `$TERM` is set to, because the shell expands `$TERM` and passes it on to `echo`.
1700
1701
1702
1703 Shells treat a lot of special characters, called meta-characters as special representations of data. The most common one is the `*` character, which represents any number of characters in a filename. These special meta-characters can be used to do filename globbing. For example, typing in `echo *` is almost the same as typing in `ls` because the shell takes all the files that match `*` and puts them on the command line for `echo` to see.
1704
1705
1706
1707 To prevent the shell from interpreting these special characters, they can be escaped from the shell by putting a backslash (`\`) character in front of them. `echo $TERM` prints whatever your terminal is set to. `echo \$TERM` prints `$TERM` as is.
1708
1709
1710
1711
1712 ### Changing Your Shell 
1713
1714 <!-- XXX: does chsh still exist? chpass will do, too -->
1715
1716 The easiest way to change your shell is to use the `chsh` command. Running `chsh` will place you into the editor that is in your `EDITOR` environment variable; if it is not set, you will be placed in `vi`. Change the ***Shell:*** line accordingly.
1717
1718
1719 You can also give `chsh` the `-s` option; this will set your shell for you, without requiring you to enter an editor. For example, if you wanted to change your shell to `bash`, the following should do the trick:
1720
1721     
1722
1723     % chsh -s /usr/pkg/bin/bash
1724
1725
1726
1727
1728
1729  **Note:** The shell that you wish to use ***must*** be present in the `/etc/shells` file. If you have installed a shell from the [ pkgsrc tree ](pkgsrc.html), then this should have been done for you already. If you installed the shell by hand, you must do this.
1730
1731
1732
1733 For example, if you installed `bash` by hand and placed it into `/usr/local/bin`, you would want to:
1734
1735
1736
1737     
1738
1739     # echo "/usr/local/bin/bash" >> /etc/shells
1740
1741
1742
1743
1744
1745 Then rerun `chsh`.
1746
1747
1748
1749
1750
1751
1752 ## Text Editors 
1753
1754
1755
1756 A lot of configuration in DragonFly is done by editing text files. Because of this, it would be a good idea to become familiar with a text editor. DragonFly comes with a few as part of the base system, and many more are available in the pkgsrc® tree.
1757
1758 The easiest and simplest editor to learn is an editor called  **ee** , which stands for easy editor. To start  **ee** , one would type at the command line `ee filename` where `filename` is the name of the file to be edited. For example, to edit `/etc/rc.conf`, type in `ee /etc/rc.conf`. Once inside of `ee`, all of the commands for manipulating the editor's functions are listed at the top of the display. The caret `^` character represents the  **Ctrl**  key on the keyboard, so `^e` expands to the key combination  **Ctrl** + **e** . To leave  **ee** , hit the  **Esc**  key, then choose leave editor. The editor will prompt you to save any changes if the file has been modified.
1759
1760 DragonFly also comes with more powerful text editors such as  **vi**  as part of the base system, while other editors, like  **emacs**  and  **vim** , are part of the pkgsrc tree. These editors offer much more functionality and power at the expense of being a little more complicated to learn. However if you plan on doing a lot of text editing, learning a more powerful editor such as  **vim**  or  **emacs**  will save you much more time in the long run.
1761
1762
1763
1764
1765 ## Devices and Device Nodes 
1766
1767 A device is a term used mostly for hardware-related activities in a system, including disks, printers, graphics cards, and keyboards. When DragonFly boots, the majority of what DragonFly displays are devices being detected. You can look through the boot messages again by viewing `/var/run/dmesg.boot`.
1768
1769 For example, `acd0` is the first IDE CDROM drive, while `kbd0` represents the keyboard.
1770
1771 Most of these devices in a UNIX® operating system must be accessed through special files called device nodes, which are located in the `/dev` directory.
1772
1773 The device nodes in the `/dev` directory are created and destroyed automatically on DragonFly >= 2.4, by means of the device file system (devfs).
1774
1775
1776
1777 ## Binary Formats 
1778
1779
1780
1781 To understand why DragonFly uses the [elf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=elf&amp;section=5) format, you must first know a little about the three currently ***dominant*** executable formats for UNIX®:
1782
1783
1784
1785
1786 * [a.out(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=a.out&amp;section=5)
1787
1788   The oldest and ***classic*** UNIX object format. It uses a short and compact header with a magic number at the beginning that is often used to characterize the format (see [a.out(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=a.out&amp;section=5) for more details). It contains three loaded segments: .text, .data, and .bss plus a symbol table and a string table.
1789
1790
1791 * <u>COFF</u>
1792
1793   The SVR3 object format. The header now comprises a section table, so you can have more than just .text, .data, and .bss sections.
1794
1795
1796 * [elf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=elf&amp;section=5)
1797
1798   The successor to COFF, featuring multiple sections and 32-bit or 64-bit possible values. One major drawback: ELF was also designed with the assumption that there would be only one ABI per system architecture. That assumption is actually quite incorrect, and not even in the commercial SYSV world (which has at least three ABIs: SVR4, Solaris, SCO) does it hold true. DragonFly tries to work around this problem somewhat by providing a utility for ***branding*** a known ELF executable with information about the ABI it is compliant with. See the manual page for [brandelf(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=brandelf&amp;section=1) for more information. DragonFly runs ELF.
1799
1800
1801
1802 So, why are there so many different formats? Back in the dim, dark past, there was simple hardware. This simple hardware supported a simple, small system. `a.out` was completely adequate for the job of representing binaries on this simple system (a PDP-11). As people ported UNIX from this simple system, they retained the `a.out` format because it was sufficient for the early ports of UNIX to architectures like the Motorola 68k, VAXen, etc.
1803
1804 Then some bright hardware engineer decided that if he could force software to do some sleazy tricks, then he would be able to shave a few gates off the design and allow his CPU core to run faster. While it was made to work with this new kind of hardware (known these days as RISC), `a.out` was ill-suited for this hardware, so many formats were developed to get to a better performance from this hardware than the limited, simple `a.out` format could offer. Things like COFF, ECOFF, and a few obscure others were invented and their limitations explored before things seemed to settle on ELF.
1805
1806 In addition, program sizes were getting huge and disks (and physical memory) were still relatively small so the concept of a shared library was born. The VM system also became more sophisticated. While each one of these advancements was done using the `a.out` format, its usefulness was stretched more and more with each new feature. In addition, people wanted to dynamically load things at run time, or to junk parts of their program after the init code had run to save in core memory and swap space. Languages became more sophisticated and people wanted code called before main automatically. Lots of hacks were done to the `a.out` format to allow all of these things to happen, and they basically worked for a time. In time, `a.out` was not up to handling all these problems without an ever increasing overhead in code and complexity. While ELF solved many of these problems, it would be painful to switch from the system that basically worked. So ELF had to wait until it was more painful to remain with `a.out` than it was to migrate to ELF.
1807
1808 ELF is more expressive than `a.out` and allows more extensibility in the base system. The ELF tools are better maintained, and offer cross compilation support, which is important to many people. ELF may be a little slower than `a.out`, but trying to measure it can be difficult. There are also numerous details that are different between the two in how they map pages, handle init code, etc. None of these are very important, but they are differences.
1809
1810
1811
1812 <!-- XXX: do we really need all this bullshit about file formats? -->
1813
1814
1815 ## For More Information 
1816
1817 ### Manual Pages 
1818
1819 The most comprehensive documentation on DragonFly is in the form of manual pages. Nearly every program on the system comes with a short reference manual explaining the basic operation and various arguments. These manuals can be viewed with the `man` command. Use of the `man` command is simple:
1820
1821     % man command
1822
1823 `command` is the name of the command you wish to learn about. For example, to learn more about `ls` command type:
1824
1825     % man ls
1826
1827 The online manual is divided up into numbered sections:
1828
1829
1830   1. User commands.
1831   1. System calls and error numbers.
1832   1. Functions in the C libraries.
1833   1. Device drivers.
1834   1. File formats.
1835   1. Games and other diversions.
1836   1. Miscellaneous information.
1837   1. System maintenance and operation commands.
1838   1. Kernel internals.
1839
1840
1841
1842 In some cases, the same topic may appear in more than one section of the online manual. For example, there is a `chmod` user command and a `chmod()` system call. In this case, you can tell the `man` command which one you want by specifying the section:
1843     
1844
1845     % man 1 chmod
1846
1847
1848 This will display the manual page for the user command `chmod`. References to a particular section of the online manual are traditionally placed in parenthesis in written documentation, so [chmod(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=chmod&section=1) refers to the `chmod` user command and [chmod(2)](http://leaf.dragonflybsd.org/cgi/web-man?command=chmod&section=2) refers to the system call.
1849
1850 This is fine if you know the name of the command and simply wish to know how to use it, but what if you cannot recall the command name? You can use `man` to search for keywords in the command descriptions by using the `-k` switch:
1851
1852    
1853
1854     % man -k mail
1855
1856
1857 With this command you will be presented with a list of commands that have the keyword ***mail*** in their descriptions. This is actually functionally equivalent to using the `apropos` command.
1858
1859 So, you are looking at all those fancy commands in `/usr/bin` but do not have the faintest idea what most of them actually do? Simply do:    
1860
1861     % cd /usr/bin
1862     % man -f *
1863
1864 or
1865    
1866
1867     % cd /usr/bin
1868     % whatis *
1869
1870 which does the same thing.
1871
1872
1873
1874 ### GNU Info Files 
1875
1876 DragonFly includes many applications and utilities produced by the Free Software Foundation (FSF). In addition to manual pages, these programs come with more extensive hypertext documents called `info` files which can be viewed with the `info` command or, if you installed  **emacs** , the info mode of  **emacs** . To use the [info(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=info&section=1) command, simply type:
1877
1878
1879     % info
1880
1881 For a brief introduction, type `h`. For a quick command reference, type `?`.
1882
1883
1884
1885
1886
1887 ## Chapter 4 Installing Applications using NetBSD's pkgsrc framework 
1888
1889
1890 <!-- XXX: possibly also mention pkgin and other fancy stuff. Or at least pkg_radd if it's not mentioned already -->
1891
1892
1893
1894 ## Overview of Software Installation 
1895
1896 If you have used a UNIX® system before you will know that the typical procedure for installing third party software goes something like this:
1897
1898
1899   1. Download the software, which might be distributed in source code format, or as a binary.
1900
1901   1. Unpack the software from its distribution format (typically a tarball compressed with [compress(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=compress&section1), [gzip(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=gzip&section=1), or [bzip2(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=bzip2&section=1)).
1902
1903   1. Locate the documentation (perhaps an `INSTALL` or `README` file, or some files in a `doc/` subdirectory) and read up on how to install the software.
1904
1905   1. If the software was distributed in source format, compile it. This may involve editing a `Makefile`, or running a `configure` script, and other work.
1906
1907   1. Test and install the software.
1908
1909
1910 And that is only if everything goes well. If you are installing a software package that was not deliberately ported to DragonFly you may even have to go in and edit the code to make it work properly. Should you want to, you can continue to install software the ***traditional*** way with DragonFly. However, DragonFly provides technology from NetBSD, which can save you a lot of effort: pkgsrc. At the time of writing, over 8,000 third party applications have been made available in this way.
1911
1912
1913 For any given application, the DragonFly Binary package for that application is a single file which you must download. The package contains pre-compiled copies of all the commands for the application, as well as any configuration files or documentation. A downloaded package file can be manipulated with DragonFly package management commands, such as [pkg_radd(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_add&section1), [pkg_delete(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_delete&section=1), [pkg_info(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_info&section=1), and so on. Installing a new application can be carried out with a single command.
1914
1915
1916
1917 In addition the pkgsrc collection supplies a collection of files designed to automate the process of compiling an application from source code. Remember that there are a number of steps you would normally carry out if you compiled a program yourself (downloading, unpacking, patching, compiling, installing). The files that make up a pkgsrc source collection contain all the necessary information to allow the system to do this for you. You run a handful of simple commands and the source code for the application is automatically downloaded, extracted, patched, compiled, and installed for you. In fact, the pkgsrc source subsystem can also be used to generate packages which can later be manipulated with `pkg_add` and the other package management commands that will be introduced shortly.
1918
1919
1920 Pkgsrc understands ***dependencies***. Suppose you want to install an application that depends on a specific library being installed. Both the application and the library have been made available through the pkgsrc collection. If you use the `pkg_add` command or the pkgsrc subsystem to add the application, both will notice that the library has not been installed, and automatically install the library first. You might be wondering why pkgsrc® bothers with both. Binary packages and the source tree both have their own strengths, and which one you use will depend on your own preference.
1921
1922
1923
1924  **Binary Package Benefits** 
1925
1926
1927
1928
1929 * A compressed package tarball is typically smaller than the compressed tarball containing the source code for the application.
1930
1931
1932 * Packages do not require any additional compilation. For large applications, such as ***Mozilla***, ***KDE***, or ***GNOME*** this can be important, particularly if you are on a slow system.
1933
1934
1935 * Packages do not require any understanding of the process involved in compiling software on DragonFly.
1936
1937
1938
1939 **Pkgsrc source Benefits** 
1940
1941
1942
1943
1944 * Binary packages are normally compiled with conservative options, because they have to run on the maximum number of systems. By installing from the source, you can tweak the compilation options to (for example) generate code that is specific to a Pentium IV or Athlon processor.
1945
1946
1947 * Some applications have compile time options relating to what they can and cannot do. For example, <i>Apache</i> can be configured with a wide variety of different built-in options. By building from the source you do not have to accept the default options, and can set them yourself. In some cases, multiple packages will exist for the same application to specify certain settings. For example, <i>vim</i> is available as a `vim` package and a `vim-gtk` package, depending on whether you have installed an X11 server. This sort of rough tweaking is possible with packages, but rapidly becomes impossible if an application has more than one or two different compile time options.
1948
1949
1950 * The licensing conditions of some software distributions forbid binary distribution. They must be distributed as source code.
1951
1952
1953 * Some people do not trust binary distributions. With source code, it is possible to check for any vulnerabilities built into the program before installing it to an otherwise secure system. Few people perform this much review, however.
1954
1955
1956 * If you have local patches, you will need the source in order to apply them.
1957
1958
1959 * Some people like having code around, so they can read it if they get bored, hack it, borrow from it (license permitting, of course), and so on.
1960
1961
1962
1963 To keep track of updated pkgsrc releases subscribe to the [NetBSD pkgsrc users mailing list](http://www.netbsd.org/MailingLists/pkgsrc-users) and the [NetBSD pkgsrc users mailing list](http://www.netbsd.org/MailingLists/tech-pkgsrc). It's also useful to watch the [DragonFly User related mailing list](http://leaf.dragonflybsd.org/mailarchive/) as errors with pkgsrc on DragonFly should be reported there.
1964
1965
1966
1967  **Warning:** Before installing any application, you should check http://www.pkgsrc.org/ for security issues related to your application.
1968
1969
1970
1971 Audit-packages will automatically check all installed applications for known vulnerabilities, a check will be also performed before any application build. Meanwhile, you can use the command `audit-packages -d` after you have installed some packages.
1972
1973
1974
1975
1976 ## Finding Your Application 
1977
1978
1979
1980 Before you can install any applications you need to know what you want, and what the application is called. DragonFly's list of available applications is growing all the time. Fortunately, there are a number of ways to find what you want:
1981
1982 Since DragonFly 1.11 [pkg_search(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_search&section1) is included in the base system.  [pkg_search(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_search&section=1) searches an already installed pkgsrc® INDEX for for a given package name.  If pkgsrc® is not installed or the INDEX file is missing, it fetches the [pkg_summary(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_summary&section=5) file.
1983
1984  **Example. Find a Package** 
1985
1986     # pkg_search fvwm
1987     fvwm-2.4.20nb1          Newer version of X11 Virtual window manager
1988     fvwm-2.5.24             Development version of X11 Virtual window manager
1989     fvwm-themes-0.6.2nb8    Configuration framework for fvwm2 with samples
1990     fvwm-wharf-1.0nb1       Copy of AfterStep's Wharf compatible with fvwm2
1991     fvwm1-1.24rnb1          Virtual window manager for X
1992
1993     
1994
1995     # pkg_search -v fvwm-2.5
1996     Name    : fvwm-2.5.24-50
1997     Dir     : wm/fvwm-devel                                     
1998     Desc    : Development version of X11 Virtual window manager 
1999     URL     : any                                               
2000     Deps    : perl>#5.0 gettext-lib>0.14.5 png>=1.2.4 libXext>=0.99.0 libX11>=1.1 libXau>=1.0 libXdmcp>=0.99 libX11>=0.99 libXft>=2.1.10 fontconfig>=2.2 freetype2>=2.1.8 
2001     freetype2>=2.1.3 expat>=1.95.7 expat>=1.95.4 freetype2>=2.1.10nb1 expat>=2.0.0nb1 fontconfig>=2.4.2 fontconfig>=2.1nb2 libXrender>=0.9.2 libXpm>=3.5.4.2 libXt>=1.0.0 
2002     libSM>=0.99.2 libICE>=0.99.1 png>=1.2.9nb2
2003
2004
2005 To get more verbose information about a package (dependencies, path in `/usr/pkgsrc`, Description) use the `-v` switch.
2006
2007 There is a pkgsrc® related web site that maintains an up-to-date searchable list of all the available applications, at [http://pkgsrc.se](http://pkgsrc.se). The packages and the corresponding source tree are divided into categories, and you may either search for an application by name (if you know it), or see all the applications available in a category.
2008
2009 ## Get the description of a package 
2010
2011 To get a more verbose description of the package use pkg_search's `-s` switch with the exact package name (e.g. as given by a normal query):
2012
2013     # pkg_search -s fvwm-2.5.24
2014     Fvwm is a very famous window manager for X, which provides a
2015     virtual/multiple disjoint desktop, a 3-D look for windows decorations,
2016     shaped/color icons. It gives a very good emulation of mwm. A nice
2017     button-bar can be used to provide convenient access to frequently used
2018     functions or programs.
2019
2020     This package is based on the unstable 2.5.x series of fvwm.  Do not
2021     use it unless comfortable running beta software.
2022
2023
2024  **Note:**  To use the `-s` switch you need a complete pkgsrc tree installed.
2025
2026
2027  
2028  ## Using the Binary Packages System 
2029
2030
2031
2032 ***DragonFly customizations contributed by Chern Lee and Adrian Nida. ***
2033
2034
2035
2036 ### Installing a Binary Package 
2037
2038 You can use the [pkg_add(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_add&section=1) utility to install a pkgsrc® software package from a local file or from a server on the network.
2039
2040 The [pkg_radd(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_radd&section=1) tool conveniently fetches and installs the requested package from one of DragonFly's pkg servers without having to know the full URL to it.
2041
2042 <!-- XXX: put in pkg_radd example, it's more meaningful; also check the url below (ftp.pkgsrc-box.org) -->
2043
2044
2045 Binary package files are distributed in `.tgz` formats. You can find them at the default location ftp://ftp.pkgsrc-box.org/packages/, among other sites. The layout of the packages is similar to that of the `/usr/pkgsrc` tree. Each category has its own directory, and every package can be found within the `All` directory.
2046
2047
2048
2049 The directory structure of the binary package system matches the source tree layout; they work with each other to form the entire package system.
2050
2051 #### Using pkg_radd 
2052
2053 Since DragonFly 1.11 you can use [pkg_radd(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_radd&section=1) to install binary packages without having to set `PACKAGESITE` or providing the complete URL.  [pkg_radd(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_radd&section=1) will handle that for you:
2054
2055     
2056
2057     # pkg_radd host
2058     #
2059
2060
2061 ### Dealing with different package versions 
2062
2063 Due to the fact that the official packages are only build for the RELEASE-Version of DragonFly, it is possible that you see a warning when installing binary packages on a DEVELOPMENT-version of DragonFly.  The warning could look like this:
2064
2065     pkg_add: Warning: package `vim-gtk2-7.1.116.tgz' was built for a different version of the OS:
2066     pkg_add: DragonFly/i386 1.10.1 (pkg) vs. DragonFly/i386 1.11.0 (this host)
2067
2068 You can safely ignore this warning.  Normally all packages build for RELEASE run fine on DEVELOPMENT unless a major API-breakage was introduced.  In this case you would see a message from the developers on the appropriate mailing list.
2069
2070 ### Managing Packages 
2071
2072 [pkg_info(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_info&section=1) is a utility that lists and describes the various packages installed.
2073
2074
2075
2076     # pkg_info
2077     digest-20050731     Message digest wrapper utility
2078     screen-4.0.2nb4     Multi-screen window manager
2079     ...
2080
2081 [pkg_version(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_version&section=1) is a utility that summarizes the versions of all installed packages. It compares the package version to the current version found in the ports tree.
2082
2083 ### Deleting a Package 
2084
2085 To remove a previously installed software package, use the [pkg_delete(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_delete&section=1) utility.
2086
2087
2088     # pkg_delete screen-4.0.3.tgz
2089
2090 ### Miscellaneous 
2091
2092 All package information is stored within the `/var/db/pkg` directory. The installed file list and descriptions of each package can be found within subdirectories of this directory.
2093
2094
2095
2096 ## Using the pkgsrc® Source Tree 
2097
2098 The following sections provide basic instructions on using the pkgsrc source tree to install or remove programs from your system.
2099
2100 ### Obtaining the pkgsrc Source Tree 
2101
2102 Before you can install pkgsrc® packages from source, you must first obtain the pkgsrc source tree--which is essentially a set of `Makefiles`, patches, and description files placed in `/usr/pkgsrc`.
2103
2104 #### CVS 
2105
2106 The primary method to obtain and keep your pkgsrc collection up to date is by using  **CVS**. This is a quick method for getting the pkgsrc collection using  **CVS** .
2107
2108 Run `cvs`:
2109
2110     # cd /usr
2111     # cvs -d anoncvs@anoncvs.us.netbsd.org:/cvsroot co pkgsrc
2112
2113  
2114 Running the following command later will download and apply all the recent changes to your source tree.
2115
2116     # cd /usr/pkgsrc
2117     # cvs up
2118
2119   
2120 #### The DragonFly Way 
2121
2122 <!-- XXX: mention our git repo of pkgsrc -->
2123
2124
2125 As of the 1.10 release, you can use the `/usr/Makefile` to checkout & update the pkgsrc tree quickly.
2126
2127 as root:
2128
2129
2130     # cd /usr
2131     # make pkgsrc-create
2132
2133 to checkout from git repository, or
2134
2135
2136     # cd /usr
2137     # make pkgsrc-update
2138
2139 to update. **NOTE**: If you use CVS instead of git please do edit the Makefile to use an appropriately speedy CVS mirror for your location and to reduce load on the main pkgsrc CVS server.
2140
2141 ### Installing Packages from Source
2142
2143 The first thing that should be explained when it comes to the source tree is what is actually meant by a ***skeleton***. In a nutshell, a source skeleton is a minimal set of files that tell your DragonFly system how to cleanly compile and install a program. Each source skeleton should include:
2144
2145 * A `Makefile`. The `Makefile` contains various statements that specify how the application should be compiled and where it should be installed on your system.
2146
2147
2148 * A `distinfo` file. This file contains information about the files that must be downloaded to build the port and their checksums, to verify that files have not been corrupted during the download using [md5(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=md5&section=1).
2149
2150
2151 * A `files` directory. This directory contains the application specific files that are needed for the programs appropriate run-time configuration.
2152
2153   This directory may also contain other files used to build the port.
2154
2155
2156 * A `patches` directory. This directory contains patches to make the program compile and install on your DragonFly system. Patches are basically small files that specify changes to particular files. They are in plain text format, and basically say <i>Remove line 10</i> or <i>Change line 26 to this ...</i>. Patches are also known as <i>diffs</i> because they are generated by the [diff(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#diff&section1) program.
2157
2158
2159 * A `DESCR` file. This is a more detailed, often multiple-line, description of the program.
2160
2161
2162 * A `PLIST` file. This is a list of all the files that will be installed by the port. It also tells the pkgsrc system what files to remove upon deinstallation.
2163
2164
2165
2166 Some pkgsrc source skeletons have other files, such as `MESSAGE`. The pkgsrc system uses these files to handle special situations. If you want more details on these files, and on pkgsrc in general, check out [The pkgsrc guide](http://www.netbsd.org/Documentation/pkgsrc/), available at the [NetBSD website](http://www.netbsd.org/).
2167
2168
2169
2170 Now that you have enough background information to know what the pkgsrc source tree is used for, you are ready to install your first compiled package. There are two ways this can be done, and each is explained below. 
2171
2172 Another way to find a particular source tree is by using the pkgsrc collection's built-in search mechanism. To use the search feature, you will need to be in the `/usr/pkgsrc` directory. Once in that directory, run `bmake search key=program-name` where `program-name` is the name of the program you want to find. This searches packages names, comments, descriptions and dependencies and can be used to find packages which relate to a particular subject if you don't know the name of the program you are looking for. For example, if you were looking for `apache2`:
2173
2174
2175     # cd /usr/pkgsrc
2176     # bmake search key="apache2"
2177     Extracting complete dependency database.  This may take a while...
2178     ....................................................................................................
2179     100
2180     ....................................................................................................
2181     200
2182     <Snip />
2183     5800
2184     ....................................................................................................
2185     5900
2186     .................................................................................................Reading database file
2187     Flattening dependencies
2188     Flattening build dependencies
2189     Generating INDEX file
2190     Indexed 5999 packages
2191     <Snip />
2192     Pkg:    apache-2.2.6nb2
2193     Path:   www/apache22
2194     Info:   Apache HTTP (Web) server, version 2
2195     Maint:  tron@NetBSD.org
2196     Index:  www
2197     B-deps: perl>#5.0 apr-util>1.2.8 apr>=1.2.8 libtool-base>=1.5.22nb1 pkg-config>=0.19 expat>=1.95.7 gmake>=3.78 gettext-lib>=0.14.5 
2198     {gettext-tools>=0.14.5,gettext>=0.10.36<0.14.5} expat>=1.95.4 expat>=2.0.0nb1 apr-util>=1.2.8nb1
2199     R-deps: perl>#5.0 apr-util>1.2.8 apr>=1.2.8 expat>=1.95.7 expat>=1.95.4 expat>=2.0.0nb1 apr-util>=1.2.8nb1
2200     Arch:   any
2201
2202
2203 The part of the output you want to pay particular attention to is the <i>Path</i> line, since that tells you where to find the source tree for the requested application. The other information provided is not needed in order to install the package, so it will not be covered here.
2204
2205 The search string is case-insensitive. Searching for <i>APACHE</i> will yield the same results as searching for <i>apache</i>.
2206
2207
2208
2209  **Note:** It should be noted that <i>Extracting [the] complete dependency database</i> does indeed take a while.
2210
2211
2212
2213  **Note:** You must be logged in as `root` to install packages.
2214
2215
2216
2217 Now that you have found an application you would like to install, you are ready to do the actual installation. The source package includes instructions on how to build source code, but does not include the actual source code. You can get the source code from a CD-ROM or from the Internet. Source code is distributed in whatever manner the software author desires. Frequently this is a tarred and gzipped file, but it might be compressed with some other tool or even uncompressed. The program source code, whatever form it comes in, is called a ***distfile***. You can get the distfile from a CD-ROM or from the Internet.
2218
2219
2220
2221  **Warning:** Before installing any application, you should be sure to have an up-to-date source tree and you should check http://www.pkgsrc.org/ for security issues related to your port.
2222
2223
2224 A security vulnerabilities check can be automatically done by  **audit-packages**  before any new application installation. This tool can be found in the pkgsrc collection ([security/audit-packages](http://pkgsrc.se/security/audit-packages)). Consider running `auditpackages -d` before installing a new package, to fetch the current vulnerabilities database. A security audit and an update of the database will be performed during the daily security system check. For more informations read the audit-packages and [periodic(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#periodic&section8) manual pages.
2225
2226
2227
2228  **Note:** It should be noted that the current setup of DragonFly requires the use of `bmake` instead of `make`. This is because the current version of make on DragonFly does not support all the parameters that NetBSD's does.
2229
2230
2231
2232  **Note:** You can save an extra step by just running `bmake install` instead of `bmake` and `bmake install` as two separate steps.
2233
2234
2235
2236  **Note:** Some shells keep a cache of the commands that are available in the directories listed in the `PATH` environment variable, to speed up lookup operations for the executable file of these commands. If you are using one of these shells, you might have to use the `rehash` command after installing a package, before the newly installed commands can be used. This is true for both shells that are part of the base-system (such as `tcsh`) and shells that are available as packages (for instance, [shells/zsh](http://pkgsrc.se/shells/zsh)).
2237
2238 <!-- XXX: mention the stuff about the pkgsrc security audit thingie -->
2239
2240 #### Installing Packages from the Internet 
2241
2242
2243
2244 As with the last section, this section makes an assumption that you have a working Internet connection. If you do not, you will need to put a copy of the distfile into `/usr/pkgsrc/distfiles` manually. Installing a package from the Internet is done exactly the same way as it would be if you already had the distfile. The only difference between the two is that the distfile is downloaded from the Internet on demand.
2245
2246
2247 Here are the steps involved:
2248
2249
2250     # cd /usr/pkgsrc/chat/ircII
2251     # bmake install clean
2252     => ircii-20040820.tar.bz2 doesn't seem to exist on this system.
2253     => Attempting to fetch ircii-20040820.tar.bz2 from ftp://ircii.warped.com/pub/ircII/.
2254     => [559843 bytes]
2255     [FTP transfer snipped]
2256     150 Opening BINARY mode data connection for 'ircii-20040820.tar.bz2' (559843 bytes).
2257     100% |***************************************|   550 KB  110.34 KB/s   00:00 ETA
2258     226 Transfer complete.
2259     [FTP transfer snipped]
2260     221 Thank you for using the FTP service on bungi.sjc.warped.net.
2261     => Checksum SHA1 OK for ircii-20040820.tar.bz2.
2262     => Checksum RMD160 OK for ircii-20040820.tar.bz2.
2263     work -> /usr/obj/pkgsrc/chat/ircII/work
2264     ##=> Extracting for ircII-20040820
2265     #########################################################################=
2266     The supported build options for this package are:
2267
2268     socks4 socks5
2269
2270     You can select which build options to use by setting PKG_DEFAULT_OPTIONS
2271     or the following variable.  Its current value is shown:
2272
2273     
2274     PKG_OPTIONS.ircII (not defined)
2275
2276     #########################################################################=
2277     #########################################################################=
2278     The following variables will affect the build process of this package,
2279     ircII-20040820.  Their current value is shown below:
2280
2281     USE_INET6 = YES
2282
2283     You may want to abort the process now with CTRL-C and change their value
2284     before continuing.  Be sure to run `/usr/pkg/bin/bmake clean' after
2285     the changes.
2286     #########################################################################=
2287     ##=> Patching for ircII-20040820
2288     ##=> Applying pkgsrc patches for ircII-20040820
2289     ##=> Overriding tools for ircII-20040820
2290     ##=> Creating toolchain wrappers for ircII-20040820
2291     ##=> Configuring for ircII-20040820
2292     ...
2293     [configure output snipped]
2294     ...
2295     ##=>  Building for ircII-20040820
2296     ...
2297     [compilation output snipped]
2298     ...
2299     ##=>  Installing for ircII-20040820
2300     ...
2301     [installation output snipped]
2302     ...
2303     ##=> [Automatic manual page handling]
2304     ##=> Registering installation for ircII-20040820
2305     ##=> Cleaning for ircII-20040820
2306     #
2307
2308
2309
2310 <!-- XXX: mention /usr/pkg/etc/mk.conf for options, etc -->
2311
2312 As you can see, the only difference are the lines that tell you where the system is fetching the package's distfile from.
2313
2314
2315
2316 The pkgsrc system uses [ftp(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ftp&section=1) to download the files, which honors various environment variables, including `FTP_PASSIVE_MODE`, `FTP_PROXY`, and `FTP_PASSWORD`. You may need to set one or more of these if you are behind a firewall, or need to use an FTP/HTTP proxy. See [ftp(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ftp&section=1) for the complete list. 
2317
2318
2319
2320 For users which cannot be connected all the time, the `bmake fetch` option is provided. Just run this command at the top level directory (`/usr/pkgsrc`) and the required files will be downloaded for you. This command will also work in the lower level categories, for example: `/usr/pkgsrc/net`. Note that if a package depends on libraries or other packages this will ***not*** fetch the distfiles of those packages as well.
2321
2322
2323
2324  **Note:** You can build all the packages in a category or as a whole by running `bmake` in the top level directory, just like the aforementioned `bmake `fetch*** method. This is dangerous, however, as some applications cannot co-exist. In other cases, some packages can install two different files with the same filename.
2325
2326
2327
2328 In some rare cases, users may need to acquire the tarballs from a site other than the `MASTER_SITES` (the location where files are downloaded from). You can override the `MASTER_SORT`, `MASTER_SORT_REGEX` and `INET_COUNTRY` options either within the `/etc/mk.conf`.
2329
2330
2331
2332  **Note:** Some packages allow (or even require) you to provide build options which can enable/disable parts of the application which are unneeded, certain security options, and other customizations. A few which come to mind are [`www/mozilla`](http://pkgsrc.se/www/mozilla), [`security/gpgme`](http://pkgsrc.se/security/gpgme), and [`mail/sylpheed-claws`](http://pkgsrc.se/mail/sylpheed-claws). To find out what build options the application you are installing requires type:
2333
2334
2335
2336     
2337
2338     # bmake show-options
2339
2340
2341
2342
2343
2344  To change the build process, either change the values of PKG_DEFAULT_OPTIONS or PKG_OPTIONS.`***PackageName***` in `/etc/mk.conf` or on the commandline as so:
2345
2346
2347
2348     
2349
2350     # bmake PKG_OPTIONS.ircII="-ssl"
2351
2352
2353
2354
2355
2356  An option is enabled if listed. It is disabled if it is prefixed by a minus sign.
2357
2358
2359
2360 #### Dealing with imake 
2361
2362
2363
2364 Some applications that use `imake` (a part of the X Window System) do not work well with `PREFIX`, and will insist on installing under `/usr/X11R6`. Similarly, some Perl ports ignore `PREFIX` and install in the Perl tree. Making these applications respect `PREFIX` is a difficult or impossible job.
2365
2366
2367
2368 ### Removing Installed Packages 
2369
2370
2371
2372 Now that you know how to install packages, you are probably wondering how to remove them, just in case you install one and later on decide that you installed the wrong program. We will remove our previous example (which was `ircII` for those of you not paying attention). As with installing packages, the first thing you must do is change to the package directory, `/usr/pkgsrc/chat/ircII`. After you change directories, you are ready to uninstall `ircII`. This is done with the `bmake deinstall` command:
2373
2374     
2375
2376     # cd /usr/pkgsrc/chat/ircII
2377     # make deinstall
2378     ##=>  Deinstalling for ircII-20040820
2379
2380
2381 That was easy enough. You have removed `ircII` from your system. If you would like to reinstall it, you can do so by running `bmake reinstall` from the `/usr/pkgsrc/chat/ircII` directory.
2382
2383
2384
2385 The `bmake deinstall` and `bmake reinstall` sequence does not work once you have run `bmake clean`. If you want to deinstall a package after cleaning, use [pkg_delete(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_delete&section=1) as discussed in the [pkgsrc-using.html Pkgsrc section of the Handbook].
2386
2387
2388
2389 ### Packages and Disk Space 
2390
2391
2392
2393 Using the pkgsrc collection can definitely eat up your disk space. For this reason you should always remember to clean up the work directories using `bmake clean`. This will remove the `work` directory after a package has been built, and installed. You can also remove the tar files from the `distfiles` directory, and remove the installed package when their use has delimited.
2394
2395
2396
2397 ### Upgrading Packages
2398
2399
2400  **Note:** Once you have updated your pkgsrc collection, before attempting a package upgrade, you should check the `/usr/pkgsrc/UPDATING` file. This file describes various issues and additional steps users may encounter and need to perform when updating a port.
2401
2402
2403
2404 Keeping your packages up to date can be a tedious job. For instance, to upgrade a package you would go to the package directory, build the package, deinstall the old package , install the new package, and then clean up after the build. Imagine doing that for five packages, tedious right? This was a large problem for system administrators to deal with, and now we have utilities which do this for us. For instance the `pkg_chk` utility will do everything for you!
2405
2406
2407
2408 pkg_chk requires a few steps in order to work correctly. They are listed here.
2409
2410     # pkg_chk -g # make initial list of installed packages
2411     # pkg_chk -r  # remove all packages that are not up to date and packages that depend on them
2412     # pkg_chk -a  # install all missing packages (use binary packages, this is the default
2413     # pkg_chk -as # install all missing packages (build from source)
2414
2415 The above process removes all packages at once and installs the missing packages one by one.This can cause longer disruption of services when the removed package has to wait a long time for its turn to get installed. "pkg_rolling-replace" replaces packages one by one and one can use it for a better way of package management. You can install "pkg_rolling-replace" by the following procedure.
2416
2417     # cd /usr/pkgsrc/pkgtools/pkg_rolling-replace/
2418     # bmake install
2419
2420 Once pkg_rolling-replace is installed you can update the packages through the following steps.
2421
2422     # cd /usr && make pkgsrc-update
2423     # pkg_rolling-replace -u
2424
2425 If some package like "bmake" does not get updated and throws an error during the above steps you can update it manually.
2426 Inside the packages directory (devel/bmake in this case)
2427
2428     # env USE_DESTDIR=full bmake package
2429     # bmake clean-depends clean
2430
2431 And Go to the packages directory and install the binary package with
2432
2433     # pkg_add -u <pkg_name> (i.e. the name of the .tgz file).
2434
2435 Also you can use "pkgin" to update software using binary packages just like apt or yum.
2436
2437     # cd /usr/pkgsrc/pkgtools/pkgin/
2438     # bmake install
2439
2440 Once "pkgin" is installed edit "/usr/pkg/etc/pkgin/repositories.conf" to contain the line ( for i386 packages ).
2441
2442     http://avalon.dragonflybsd.org/packages/i386/DragonFly-2.5/stable/All
2443
2444 Then you can run the following commands to get the packages updated.
2445
2446     # pkgin update
2447     # pkgin full-upgrade 
2448
2449     
2450     
2451     ## Post-installation Activities 
2452
2453
2454
2455 After installing a new application you will normally want to read any documentation it may have included, edit any configuration files that are required, ensure that the application starts at boot time (if it is a daemon), and so on.
2456
2457
2458
2459 The exact steps you need to take to configure each application will obviously be different. However, if you have just installed a new application and are wondering ***What now?*** these tips might help:
2460
2461
2462
2463
2464 Use [pkg_info(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_info&section=1) to find out which files were installed, and where. For example, if you have just installed Foo_Package version 1.0.0, then this command
2465
2466     # pkg_info -L foopackage-1.0.0 | less
2467
2468 will show all the files installed by the package. Pay special attention to files in `man/` directories, which will be manual pages, `etc/` directories, which will be configuration files, and `doc/`, which will be more comprehensive documentation. If you are not sure which version of the application was just installed, a command like this
2469
2470       
2471
2472     pkg_info | grep -i foopackage
2473
2474   
2475 will find all the installed packages that have <i>foopackage</i> in the package name. Replace <i>foopackage</i> in your command line as necessary.
2476
2477
2478 Once you have identified where the application's manual pages have been installed, review them using [man(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=man&section=1). Similarly, look over the sample configuration files, and any additional documentation that may have been provided.
2479
2480
2481 If the application has a web site, check it for additional documentation, frequently asked questions, and so forth. If you are not sure of the web site address it may be listed in the output from
2482
2483       
2484
2485     # pkg_info foopackage-1.0.0
2486
2487   
2488 A `WWW:` line, if present, should provide a URL for the application's web site.
2489
2490
2491 Packages that should start at boot (such as Internet servers) will usually install a sample script in `/usr/pkg/etc/rc.d`. You should review this script for correctness and edit or rename it if needed.
2492
2493
2494
2495
2496
2497
2498 ## Dealing with Broken Packages 
2499
2500
2501
2502 If you come across a package that does not work for you, there are a few things you can do, including:
2503
2504
2505
2506   1. Fix it! The [pkgsrc Guide](http://www.netbsd.org/Documentation/pkgsrc/) includes detailed information on the ***pkgsrc®*** infrastructure so that you can fix the occasional broken package or even submit your own!
2507
2508   1. Gripe--***by email only***! Send email to the maintainer of the package first. Type `bmake maintainer` or read the `Makefile` to find the maintainer's email address. Remember to include the name and version of the port (send the `$NetBSD:` line from the `Makefile`) and the output leading up to the error when you email the maintainer. If you do not get a response from the maintainer, you can try [users](http://leaf.dragonflybsd.org/mailarchive/) .
2509
2510   1. Grab the package from an FTP site near you. The ***master*** package collection is on `packages.stura.uni-rostock.de` in the [All directory](ftp://packages.stura.uni-rostock.de/pkgsrc-current/DragonFly/RELEASE/i386/All/). These are more likely to work than trying to compile from source and are a lot faster as well. Use the [pkg_add(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_add&section=1) program to install the package on your system.
2511
2512
2513
2514
2515
2516
2517
2518 CategoryHandbook
2519
2520 CategoryHandbook-pkgsrc
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540 # The X Window System 
2541
2542
2543
2544 ***Updated for X.Org's X11 server by Ken Tom and Marc Fonvieille. Updated for DragonFly by Victor Balada Diaz.***
2545
2546
2547 ## Synopsis 
2548
2549 DragonFly uses X11 to provide users with a powerful graphical user interface. X11 is an open-source implementation of the X Window System that includes both  **X.org**  and  **XFree86™** . DragonFly default official flavor is  **X.org** , the X11 server developed by the X.Org Foundation. This chapter will cover the installation and configuration of X11 with emphasis on  **X.org** . For more information on the video hardware that X11 supports, check either the [X.org](http://www.x.org/) or [XFree86](http://www.XFree86.org/) web sites.
2550
2551
2552
2553 After reading this chapter, you will know:
2554
2555
2556
2557
2558 * The various components of the X Window System, and how they interoperate.
2559 * How to install and configure X11.
2560 * How to install and use different window managers.
2561 * How to use True***Type® fonts in X11.
2562 * How to set up your system for graphical logins ( **XDM** ).
2563
2564
2565
2566 Before reading this chapter, you should:
2567
2568 * Know how to install additional third-party software. Compare the pkgsrc chapter of the handbook.
2569
2570 **Note:** This chapter covers the installation and the configuration of both  **X.org**  and  **XFree86**  X11 servers. For the most part, configuration files, commands and syntaxes are identical. In the case where there are differences, both  **X.org**  and  **XFree86**  syntaxes will be shown.
2571
2572
2573
2574
2575
2576
2577 # Understanding X 
2578
2579 ## The Window Manager 
2580
2581
2582
2583 The X design philosophy is much like the UNIX design philosophy, ***tools, not policy***. This means that X does not try to dictate how a task is to be accomplished. Instead, tools are provided to the user, and it is the user's responsibility to decide how to use those tools. This philosophy extends to X not dictating what windows should look like on screen, how to move them around with the mouse, what keystrokes should be used to move between windows (i.e.,  **Alt** + **Tab** , in the case of Microsoft Windows), what the title bars on each window should look like, whether or not they have close buttons on them, and so on.
2584
2585
2586
2587 Instead, X delegates this responsibility to an application called a ***Window Manager***. There are dozens of window managers available for X: ***'After***Step***',  **Blackbox** ,  **ctwm** ,  **Enlightenment** ,  **fvwm** ,  **Sawfish** ,  **twm** ,  **Window Maker** , and more. Each of these window managers provides a different look and feel; some of them support ***virtual desktops***; some of them allow customized keystrokes to manage the desktop; some have a ***Start*** button or similar device; some are ***themeable***, allowing a complete change of look-and-feel by applying a new theme. These window managers, and many more, are available in the `x11-wm` category of the Ports Collection.
2588
2589
2590
2591 In addition, the  **KDE**  and  **GNOME**  desktop environments both have their own window managers which integrate with the desktop. Each window manager also has a different configuration mechanism; some expect configuration file written by hand, others feature GUI tools for most of the configuration tasks; at least one ( **Sawfish** ) has a configuration file written in a dialect of the Lisp language.
2592
2593
2594
2595
2596
2597 # Installing X1
2598
2599 **X.org**  or  **XFree86™**  may be installed on DragonFly. DragonFly doesn't force a default implementation, but recommends  **X.org** .  **X.org**  is the X server of the open source X Window System implementation released by the X.Org Foundation and is based on the code of  **XFree86 4.4RC2**  and !X11R6.6.  **X.org**  is currently available in the DragonFly pkgsrc framework.
2600
2601 To build and install  **X.org**  from the pkgsrc framework:
2602     # echo "X11_TYPE=modular" >> /etc/mk.conf
2603
2604
2605 Now 5 different packages need to be built and installed:
2606
2607     # cd /usr/pkgsrc/x11/modular-xorg-server
2608     # bmake install clean
2609     # cd /usr/pkgsrc/meta-pkgs/modular-xorg-drivers
2610     # bmake install clean
2611     # cd /usr/pkgsrc/meta-pkgs/modular-xorg-fonts
2612     # bmake install clean
2613     # cd /usr/pkgsrc/meta-pkgs/modular-xorg-libs
2614     # bmake install clean
2615     # cd /usr/pkgsrc/meta-pkgs/modular-xorg-apps
2616     # bmake install clean
2617
2618
2619
2620 Alternatively, X11 can be installed directly from packages. Binary packages to use with [pkg_radd(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_radd&section=1) tool are also available for X11.So to fetch and install the package of  **X.org**, type:
2621   
2622
2623     # pkg_radd modular-xorg-server
2624     # pkg_radd modular-xorg-drivers
2625     # pkg_radd modular-xorg-libs
2626     # pkg_radd modular-xorg-apps
2627     # pkg_radd modular-xorg-fonts
2628
2629
2630 **Note:** The examples above will install the complete X11 distribution including the server, drivers, fonts etc. Separate packages and ports of X11 are also available.
2631
2632
2633
2634
2635 ----
2636
2637
2638
2639 ## 5.4 X11 Configuration 
2640
2641
2642
2643           ***Contributed by Christopher Shumway. ***
2644
2645
2646
2647 ### 5.4.1 Before Starting 
2648
2649
2650
2651 Before configuration of X11 the following information about the target system is needed:
2652
2653
2654
2655
2656 * Monitor specifications
2657
2658
2659 * Video Adapter chipset
2660
2661
2662 * Video Adapter memory
2663
2664
2665
2666 The specifications for the monitor are used by X11 to determine the resolution and refresh rate to run at. These specifications can usually be obtained from the documentation that came with the monitor or from the manufacturer's website. There are two ranges of numbers that are needed, the horizontal scan rate and the vertical synchronization rate.
2667
2668
2669
2670 The video adapter's chipset defines what driver module X11 uses to talk to the graphics hardware. With most chipsets, this can be automatically determined, but it is still useful to know in case the automatic detection does not work correctly.
2671
2672
2673
2674 Video memory on the graphic adapter determines the resolution and color depth which the system can run at. This is important to know so the user knows the limitations of the system.
2675
2676
2677
2678 ### 5.4.2 Configuring X11 
2679
2680
2681
2682 As of version 7.3, Xorg can often work without any configuration file by simply typing at prompt:
2683
2684     
2685
2686     % startx
2687
2688
2689
2690
2691 If this does not work, or if the default configuration is not acceptable, then X11 must be configured manually. Configuration of X11 is a multi-step process. The first step is to build an initial configuration file. As the super user, simply run:
2692
2693    
2694
2695     # Xorg -configure
2696
2697
2698 This will generate an X11 configuration skeleton file in the `/root` directory called `xorg.conf.new` (whether you [su(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=su&amp;section=1) or do a direct login affects the inherited supervisor `$HOME` directory variable). The X11 program will attempt to probe the graphics hardware on the system and write a configuration file to load the proper drivers for the detected hardware on the target system.
2699
2700
2701
2702 The next step is to test the existing configuration to verify that  **X.org**  can work with the graphics hardware on the target system. To perform this task, type:
2703
2704    
2705
2706     # Xorg -config xorg.conf.new
2707
2708
2709 If a black and grey grid and an X mouse cursor appear, the configuration was successful. To exit the test, just press  **Ctrl** + **Alt** + **Backspace**  simultaneously.
2710
2711
2712
2713 **Note:** If the mouse does not work, you will need to first configure it before proceeding. This can usually be achieved by just using `/dev/sysmouse` as the input device in the config file and enabling `moused`:
2714
2715         # rcenable moused
2716
2717
2718
2719 Next, tune the `xorg.conf.new` configuration file to taste. Open the file in a text editor such as [vi(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=vi&section=1) or [ee(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ee&amp;section=1). First, add the frequencies for the target system's monitor. These are usually expressed as a horizontal and vertical synchronization rate. These values are added to the `xorg.conf.new` file under the `"Monitor"` section:
2720
2721     
2722
2723     Section "Monitor"
2724             Identifier   "Monitor0"
2725             VendorName   "Monitor Vendor"
2726             ModelName    "Monitor Model"
2727             HorizSync    30-107
2728             VertRefresh  48-120
2729     EndSection
2730
2731
2732
2733 The `HorizSync` and `VertRefresh` keywords may be missing in the configuration file. If they are, they need to be added, with the correct horizontal synchronization rate placed after the `HorizSync` keyword and the vertical synchronization rate after the `VertRefresh` keyword. In the example above the target monitor's rates were entered.
2734
2735
2736
2737 X allows DPMS (Energy Star) features to be used with capable monitors. The [xset(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=xset&section=1) program controls the time-outs and can force standby, suspend, or off modes. If you wish to enable DPMS features for your monitor, you must add the following line to the monitor section:
2738
2739             Option       "DPMS"
2740
2741
2742
2743 While the `xorg.conf.new` configuration file is still open in an editor, select the default resolution and color depth desired. This is defined in the `"Screen"` section:
2744
2745
2746
2747     
2748
2749     Section "Screen"
2750             Identifier "Screen0"
2751             Device     "Card0"
2752             Monitor    "Monitor0"
2753             DefaultDepth 24
2754             SubSection "Display"
2755                     Viewport  0 0
2756                     Depth     24
2757                     Modes     "1024x768"
2758             EndSubSection
2759     EndSection
2760
2761
2762 The `DefaultDepth` keyword describes the color depth to run at by default. This can be overridden with the `-depth` command line switch to [Xorg(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=xorg&section=1). The `Modes` keyword describes the resolution to run at for the given color depth. Note that only VESA standard modes are supported as defined by the target system's graphics hardware. In the example above, the default color depth is twenty-four bits per pixel. At this color depth, the accepted resolution is 1024 by 768 pixels.
2763
2764
2765 Finally, write the configuration file and test it using the test mode given above.
2766
2767
2768 **Note:** One of the tools available to assist you during troubleshooting process are the X11 log files, which contain information on each device that the X11 server attaches to.  **X.org**  log file names are in the format of `/var/log/Xorg.0.log`. The exact name of the log can vary from `Xorg.0.log` to `Xorg.8.log` and so forth.
2769
2770
2771
2772 If all is well, the configuration file needs to be installed in a common location where [Xorg(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=xorg&section=1) can find it. This is typically `/etc/X11/xorg.conf` or `/usr/pkg/xorg/lib/X11/xorg.conf`.
2773
2774
2775
2776     # cp xorg.conf.new /etc/X11/xorg.conf
2777
2778
2779
2780 The X11 configuration process is now complete. You can start  **X.org**  with [startx(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=startx&section=1). The X11 server may also be started with the use of [xdm(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=xdm&section=1).
2781
2782
2783 **Note:** There is also a graphical configuration tool, [xorgcfg(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=xorgcfg&section=1), that comes with the X11 distribution. It allows you to interactively define your configuration by choosing the appropriate drivers and settings. This program can be invoked from the console, by typing the command `xorgcfg -textmode`. For more details, refer to the [xorgcfg(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=xorgcfg&section=1) manual page.
2784
2785
2786 Alternatively, there is also a tool called [xorgconfig(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=xorgconfig&section=1), this program is a console utility that is less user friendly, but it may work in situations where the other tools do not.
2787
2788
2789
2790 ### 5.4.3 Advanced Configuration Topics 
2791
2792
2793
2794 #### 5.4.3.1 Configuration with Intel® i810 Graphics Chipsets 
2795
2796
2797
2798 Configuration with Intel® i810 integrated chipsets requires the `agpgart` AGP programming interface for X11 to drive the card. See the [agp(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=agp&amp;section=4) driver manual page for more information.
2799
2800
2801 This will allow configuration of the hardware as any other graphics board. Note on systems without the [agp(4)](http://leaf.dragonflybsd.org/cgi/web-man?command#agp&section4) driver compiled in the kernel, trying to load the module with [kldload(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=kldload&section=8) will not work. This driver has to be in the kernel at boot time through being compiled in or using `/boot/loader.conf`.
2802
2803
2804 **Note:** If you are using  **XFree86 4.1.0**  (or later) and messages about unresolved symbols like `fbPictureInit` appear, try adding the following line after `Driver "i810"` in the X11 configuration file:
2805
2806               Option "NoDDC"
2807
2808
2809
2810
2811
2812 ----
2813
2814
2815
2816
2817
2818
2819 # 5.5 Using Fonts in X11 
2820 <!-- XXX: do we really need this? -->
2821
2822
2823  ***Contributed by Murray Stokely. ***
2824
2825
2826
2827 ## 5.5.1 Type1 Fonts 
2828
2829
2830
2831  The default fonts that ship with X11 are less than ideal for typical desktop publishing applications. Large presentation fonts show up jagged and unprofessional looking, and small fonts in  **Netscape®**  are almost completely unintelligible. However, there are several free, high quality Type1 (Post***Script®) fonts available which can be readily used with X11. For instance, the Freefonts collection (['fonts/freefonts'](http://pkgsrc.se/fonts/freefonts)) includes a lot of fonts, but most of them are intended for use in graphics software such as the  **Gimp** , and are not complete enough to serve as screen fonts. In addition, X11 can be configured to use True***Type® fonts with a minimum of effort. For more details on this, see the [X(7)](http://leaf.dragonflybsd.org/cgi/web-man?command=X&section=7) manual page or the [ section on TrueType fonts](x-fonts.html#TRUETYPE).
2832
2833
2834
2835  To install the Freefonts font collection from the pkgsrc framework, run the following commands:
2836
2837
2838
2839      
2840
2841     # cd /usr/pkgsrc/fonts/freefonts
2842
2843     # bmake install clean
2844
2845
2846
2847
2848
2849  And likewise with the other collections. To have the X server detect these fonts, add an appropriate line to the X server configuration file in `/etc/X11/xorg.conf`, which reads:
2850
2851
2852
2853      
2854
2855     FontPath "/usr/pkg/lib/X11/fonts/freefont/"
2856
2857
2858
2859
2860
2861  Alternatively, at the command line in the X session run:
2862
2863
2864
2865      
2866
2867     % xset fp+ /usr/pkg/lib/X11/fonts/freefont/
2868
2869     % xset fp rehash
2870
2871
2872
2873
2874
2875  This will work but will be lost when the X session is closed, unless it is added to the startup file (`~/.xinitrc` for a normal `startx` session, or `~/.xsession` when logging in through a graphical login manager like  **XDM** ). A third way is to use the new `/usr/pkg/xorg/etc/fonts/local.conf` file: see the section on [ anti-aliasing](x-fonts.html#ANTIALIAS).
2876
2877
2878
2879 ## 5.5.2 TrueType® Fonts 
2880
2881
2882
2883   **X.org**  has built in support for rendering True***Type fonts. There are two different modules that can enable this functionality. The freetype module is used in this example because it is more consistent with the other font rendering back-ends. To enable the freetype module just add the following line to the `"Module"` section of the `/etc/X11/xorg.conf` file.
2884
2885
2886
2887      
2888
2889     Load  "freetype"
2890
2891
2892
2893
2894
2895  Now make a directory for the True***Type fonts (for example, `/usr/pkg/xorg/lib/X11/fonts/TrueType`) and copy all of the True***Type fonts into this directory. Keep in mind that True***Type fonts cannot be directly taken from a Macintosh®; they must be in UNIX®/MS-DOS®/Windows® format for use by X11. Once the files have been copied into this directory, use  **ttmkfdir**  to create a `fonts.dir` file, so that the X font renderer knows that these new files have been installed. 'ttmkfdir' is available from the pkgsrc framework as [`fonts/ttmkfdir2`](http://pkgsrc.se/fonts/ttmkfdir2).
2896
2897
2898
2899      
2900
2901     # cd /usr/pkg/xorg/lib/X11/fonts/TrueType
2902
2903     # ttmkfdir -o fonts.dir
2904
2905
2906
2907
2908
2909  Now add the True***Type directory to the font path. This is just the same as described above for [ Type1](x-fonts.html#TYPE1) fonts, that is, use
2910
2911
2912
2913     
2914
2915     % xset fp+ /usr/pkg/xorg/lib/X11/fonts/TrueType
2916
2917     % xset fp rehash
2918
2919
2920
2921
2922
2923  or add a `FontPath` line to the `xorg.conf` file.
2924
2925
2926
2927  That's it. Now  **Netscape** ,  **Gimp** , ***'Star***Office™***', and all of the other X applications should now recognize the installed True***Type fonts. Extremely small fonts (as with text in a high resolution display on a web page) and extremely large fonts (within  **Star`Office** ) will look much better now.
2928
2929
2930
2931 ## 5.5.3 Anti-Aliased Fonts 
2932
2933
2934
2935  ***Updated by Joe Marcus Clarke. ***
2936
2937
2938
2939  Anti-aliasing has been available in X11 since  **XFree86**  4.0.2. However, font configuration was cumbersome before the introduction of  **XFree86**  4.3.0. Beginning with  **XFree86**  4.3.0, all fonts in X11 that are found in `/usr/pkg/xorg/lib/X11/fonts/` and `~/.fonts/` are automatically made available for anti-aliasing to Xft-aware applications. Not all applications are Xft-aware, but many have received Xft support. Examples of Xft-aware applications include Qt 2.3 and higher (the toolkit for the  **KDE**  desktop), GTK+ 2.0 and higher (the toolkit for the  **GNOME**  desktop), and  **Mozilla**  1.2 and higher.
2940
2941
2942
2943  In order to control which fonts are anti-aliased, or to configure anti-aliasing properties, create (or edit, if it already exists) the file `/usr/pkg/xorg/lib/etc/fonts/local.conf`. Several advanced features of the Xft font system can be tuned using this file; this section describes only some simple possibilities. For more details, please see [fonts-conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=fonts-conf&section=5).
2944
2945
2946
2947  This file must be in XML format. Pay careful attention to case, and make sure all tags are properly closed. The file begins with the usual XML header  followed by a DOCTYPE definition, and then the `<fontconfig>` tag:
2948
2949
2950
2951      
2952
2953           <?xml version="1.0"?>;
2954
2955           <!DOCTYPE fontconfig SYSTEM "fonts.dtd">
2956
2957           <fontconfig>
2958
2959
2960
2961
2962
2963  As previously stated, all fonts in `/usr/pkg/xorg/lib/X11/fonts/` as well as `~/.fonts/` are already made available to Xft-aware applications. If you wish to add another directory outside of these two directory trees, add a line similar to the following to `/usr/pkg/lib/etc/fonts/local.conf`:
2964
2965
2966
2967      
2968
2969     <dir>/path/to/my/fonts</dir>;
2970
2971
2972
2973
2974
2975  After adding new fonts, and especially new font directories, you should run the following command to rebuild the font caches:
2976
2977
2978
2979      
2980
2981     # fc-cache -f
2982
2983
2984
2985
2986
2987  Anti-aliasing makes borders slightly fuzzy, which makes very small text more readable and removes "staircases" from large text, but can cause eyestrain if applied to normal text. To exclude font sizes smaller than 14 point from anti-aliasing, include these lines:
2988
2989
2990
2991      
2992
2993             <match target="font">
2994
2995                 <test name#"size" compare"less">
2996
2997                     <double>14</double>
2998
2999                 </test>
3000
3001                 <edit name#"antialias" mode"assign">
3002
3003                     <bool>false</bool>
3004
3005                 </edit>
3006
3007             </match>
3008
3009             <match target="font">
3010
3011                 <test name#"pixelsize" compare"less" qual="any">
3012
3013                     <double>14</double>
3014
3015                 </test>
3016
3017                 <edit mode#"assign" name"antialias">
3018
3019                     <bool>false</bool>
3020
3021                 </edit>
3022
3023             </match>
3024
3025
3026
3027
3028
3029  Spacing for some monospaced fonts may also be inappropriate with anti-aliasing. This seems to be an issue with  **KDE** , in particular. One possible fix for this is to force the spacing for such fonts to be 100. Add the following lines:
3030
3031
3032
3033      
3034
3035            <match target#"pattern" name"family">
3036
3037                <test qual#"any" name"family">
3038
3039                    <string>fixed</string>
3040
3041                </test>
3042
3043                <edit name#"family" mode"assign">
3044
3045                    <string>mono</string>
3046
3047                </edit>
3048
3049             </match>
3050
3051             <match target#"pattern" name"family">
3052
3053                 <test qual#"any" name"family">
3054
3055                     <string>console</string>
3056
3057                 </test>
3058
3059                 <edit name#"family" mode"assign">
3060
3061                     <string>mono</string>
3062
3063                 </edit>
3064
3065             </match>
3066
3067
3068
3069
3070
3071  (this aliases the other common names for fixed fonts as `"mono"`), and then add:
3072
3073
3074
3075      
3076
3077              <match target#"pattern" name"family">
3078
3079                  <test qual#"any" name"family">
3080
3081                      <string>mono</string>
3082
3083                  </test>
3084
3085                  <edit name#"spacing" mode"assign">
3086
3087                      <int>100</int>
3088
3089                  </edit>
3090
3091              </match>
3092
3093
3094
3095
3096
3097  Certain fonts, such as Helvetica, may have a problem when anti-aliased. Usually this manifests itself as a font that seems cut in half vertically. At worst, it may cause applications such as  **Mozilla**  to crash. To avoid this, consider adding the following to `local.conf`:
3098
3099
3100
3101      
3102
3103              <match target#"pattern" name"family">
3104
3105                  <test qual#"any" name"family">
3106
3107                      <string>Helvetica</string>
3108
3109                  </test>
3110
3111                  <edit name#"family" mode"assign">
3112
3113                      <string>sans-serif</string>
3114
3115                  </edit>
3116
3117              </match>
3118
3119
3120
3121
3122
3123  Once you have finished editing `local.conf` make sure you end the file with the `</fontconfig>` tag. Not doing this will cause your changes to be ignored.
3124
3125
3126
3127  The default font set that comes with X11 is not very desirable when it comes to anti-aliasing. A much better set of default fonts can be found in the ['fonts/vera-ttf'](http://pkgsrc.se/fonts/vera-ttf) port. This port will install a `/usr/pkg/lib/etc/fonts/local.conf` file if one does not exist already. If the file does exist, the port will create a `/usr/pkg/lib/etc/fonts/local.conf-vera ` file. Merge the contents of this file into `/usr/pkg/lib/etc/fonts/local.conf`, and the Bitstream fonts will automatically replace the default X11 Serif, Sans Serif, and Monospaced fonts.
3128
3129
3130
3131  Finally, users can add their own settings via their personal `.fonts.conf` files. To do this, each user should simply create a `~/.fonts.conf`. This file must also be in XML format.
3132
3133
3134
3135  One last point: with an LCD screen, sub-pixel sampling may be desired. This basically treats the (horizontally separated) red, green and blue components separately to improve the horizontal resolution; the results can be dramatic. To enable this, add the line somewhere in the `local.conf` file:
3136
3137
3138
3139      
3140
3141              <match target="font">
3142
3143                  <test qual#"all" name"rgba">
3144
3145                      <const>unknown</const>
3146
3147                  </test>
3148
3149                  <edit name#"rgba" mode"assign">
3150
3151                      <const>rgb</const>
3152
3153                  </edit>
3154
3155              </match>
3156
3157
3158
3159
3160
3161    **Note:** Depending on the sort of display, `rgb` may need to be changed to `bgr`, `vrgb` or `vbgr`: experiment and see which works best.
3162
3163
3164
3165
3166
3167  Anti-aliasing should be enabled the next time the X server is started. However, programs must know how to take advantage of it. At present, the Qt toolkit does, so the entire  **KDE**  environment can use anti-aliased fonts. GTK+ and  **GNOME**  can also be made to use anti-aliasing via the "Font" capplet (see [x11-wm.html#X11-WM-GNOME-ANTIALIAS Section 5.7.1.3] for details). By default,  **Mozilla**  1.2 and greater will automatically use anti-aliasing. To disable this, rebuild  **Mozilla**  with the `-DWITHOUT_XFT` flag.
3168
3169
3170 ----
3171
3172
3173
3174 # 5.6 The X Display Manager 
3175
3176  ***Contributed by Seth Kingsley.***
3177
3178
3179
3180 ## 5.6.1 Overview 
3181
3182
3183
3184  The X Display Manager ( **XDM** ) is an optional part of the X Window System that is used for login session management. This is useful for several types of situations, including minimal "X Terminals", desktops, and large network display servers. Since the X Window System is network and protocol independent, there are a wide variety of possible configurations for running X clients and servers on different machines connected by a network.  **XDM**  provides a graphical interface for choosing which display server to connect to, and entering authorization information such as a login and password combination.
3185
3186
3187
3188  Think of  **XDM**  as providing the same functionality to the user as the [getty(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=getty&section=8) utility (see [ Section 17.3.2](term.html#TERM-CONFIG) for details). That is, it performs system logins to the display being connected to and then runs a session manager on behalf of the user (usually an X window manager).  **XDM**  then waits for this program to exit, signaling that the user is done and should be logged out of the display. At this point,  **XDM**  can display the login and display chooser screens for the next user to login.
3189
3190
3191
3192 ## 5.6.2 Using XDM 
3193
3194
3195
3196  The  **XDM**  daemon program is located in `/usr/pkg/xorg/bin/xdm`. This program can be run at any time as `root` and it will start managing the X display on the local machine. If  **XDM**  is to be run every time the machine boots up, a convenient way to do this is by adding an entry to `/etc/ttys`. For more information about the format and usage of this file, see [ Section 17.3.2.1](term.html#TERM-ETCTTYS). There is a line in the default `/etc/ttys` file for running the  **XDM**  daemon on a virtual terminal:
3197
3198
3199
3200      
3201
3202     ttyv8   "/usr/pkg/xorg/bin/xdm -nodaemon"  xterm   off secure
3203
3204
3205
3206
3207
3208  By default this entry is disabled; in order to enable it change field 5 from `off` to `on` and restart [init(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=init&section=8) using the directions in [ Section 17.3.2.2](term.html#TERM-HUP). The first field, the name of the terminal this program will manage, is `ttyv8`. This means that  **XDM**  will start running on the 9th virtual terminal.
3209
3210
3211
3212 ## 5.6.3 Configuring XDM 
3213
3214
3215
3216  The  **XDM**  configuration directory is located in `/var/lib/xdm`. The sample configuration files are in `/usr/pkg/share/examples/xorg/xdm/`, in this directory there are several files used to change the behavior and appearance of  **XDM** . Typically these files will be found:
3217
3218
3219 [[!table  data="""
3220 <tablestyle="width:100%">  **File**  |  **Description**
3221 <tablestyle="width:100%"> `Xaccess` | Client authorization ruleset.
3222 `Xresources` | Default X resource values.
3223 `Xservers` | List of remote and local displays to manage.
3224 `Xsession` | Default session script for logins.
3225 `Xsetup_`* | Script to launch applications before the login interface.
3226 `xdm-config` | Global configuration for all displays running on this machine.
3227 `xdm-errors` | Errors generated by the server program.
3228 `xdm-pid` | The process ID of the currently running XDM. |
3229
3230 """]]
3231
3232
3233  Also in this directory are a few scripts and programs used to set up the desktop when  **XDM**  is running. The purpose of each of these files will be briefly described. The exact syntax and usage of all of these files is described in [xdm(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=xdm&section=1).
3234
3235
3236
3237  The default configuration is a simple rectangular login window with the hostname of the machine displayed at the top in a large font and "Login:" and "Password:" prompts below. This is a good starting point for changing the look and feel of  **XDM**  screens.
3238
3239
3240
3241 ### 5.6.3.1 Xaccess 
3242
3243
3244
3245  The protocol for connecting to  **XDM**  controlled displays is called the X Display Manager Connection Protocol (XDMCP). This file is a ruleset for controlling XDMCP connections from remote machines. It is ignored unless the `xdm-config` is changed to listen for remote connections. By default, it does not allow any clients to connect.
3246
3247
3248
3249 ### 5.6.3.2 Xresources 
3250
3251
3252
3253  This is an application-defaults file for the display chooser and the login screens. This is where the appearance of the login program can be modified. The format is identical to the app-defaults file described in the X11 documentation.
3254
3255
3256
3257 ### 5.6.3.3 Xservers 
3258
3259
3260
3261  This is a list of the remote displays the chooser should provide as choices.
3262
3263
3264
3265 ### 5.6.3.4 Xsession 
3266
3267
3268
3269  This is the default session script for  **XDM**  to run after a user has logged in. Normally each user will have a customized session script in `~/.xsession` that overrides this script.
3270
3271
3272
3273 ### 5.6.3.5 Xsetup_* 
3274
3275
3276
3277  These will be run automatically before displaying the chooser or login interfaces. There is a script for each display being used, named `Xsetup_` followed by the local display number (for instance `Xsetup_0`). Typically these scripts will run one or two programs in the background such as `xconsole`.
3278
3279
3280
3281 ### 5.6.3.6 xdm-config 
3282
3283
3284
3285  This contains settings in the form of app-defaults that are applicable to every display that this installation manages.
3286
3287
3288
3289 ### 5.6.3.7 xdm-errors 
3290
3291
3292
3293  This contains the output of the X servers that  **XDM**  is trying to run. If a display that  **XDM**  is trying to start hangs for some reason, this is a good place to look for error messages. These messages are also written to the user's `~/.xsession-errors` file on a per-session basis.
3294
3295
3296
3297 ## 5.6.4 Running a Network Display Server 
3298
3299
3300
3301  In order for other clients to connect to the display server, edit the access control rules, and enable the connection listener. By default these are set to conservative values. To make  **XDM**  listen for connections, first comment out a line in the `xdm-config` file:
3302
3303
3304
3305      
3306
3307     ! SECURITY: do not listen for XDMCP or Chooser requests
3308
3309     ! Comment out this line if you want to manage X terminals with xdm
3310
3311     DisplayManager.requestPort:     0
3312
3313
3314
3315
3316
3317  and then restart  **XDM** . Remember that comments in app-defaults files begin with a "!" character, not the usual "#". More strict access controls may be desired. Look at the example entries in `Xaccess`, and refer to the [xdm(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=xdm&section=1) manual page for further information.
3318
3319
3320
3321 ## 5.6.5 Replacements for XDM 
3322
3323
3324
3325  Several replacements for the default  **XDM**  program exist. One of them,  **kdm**  (bundled with  **KDE** ) is described later in this chapter. The  **kdm**  display manager offers many visual improvements and cosmetic frills, as well as the functionality to allow users to choose their window manager of choice at login time.
3326
3327
3328 ----
3329
3330
3331
3332 # 5.7 Desktop Environments 
3333
3334  ***Contributed by Valentino Vaschetto. ***
3335
3336  This section describes the different desktop environments available for X on FreeBSD. A ***desktop environment*** can mean anything ranging from a simple window manager to a complete suite of desktop applications, such as  **KDE**  or  **GNOME** .
3337
3338
3339
3340 ## 5.7.1 GNOME 
3341
3342
3343
3344 ### 5.7.1.1 About GNOME 
3345
3346
3347
3348    **GNOME**  is a user-friendly desktop environment that enables users to easily use and configure their computers.  **GNOME**  includes a panel (for starting applications and displaying status), a desktop (where data and applications can be placed), a set of standard desktop tools and applications, and a set of conventions that make it easy for applications to cooperate and be consistent with each other. Users of other operating systems or environments should feel right at home using the powerful graphics-driven environment that  **GNOME**  provides.
3349
3350
3351
3352 ### 5.7.1.2 Installing GNOME 
3353
3354
3355
3356    **GNOME**  can be easily installed from a package or from the pkgsrc framework:
3357
3358
3359
3360   To install the  **GNOME**  package from the network, simply type:
3361
3362     # pkg_radd gnome
3363
3364
3365
3366
3367
3368   To build  **GNOME**  from source, use the ports tree:
3369
3370       
3371
3372     # cd /usr/pkgsrc/meta-pkgs/gnome
3373
3374     # bmake install clean
3375
3376
3377
3378   Once  **GNOME**  is installed, the X server must be told to start  **GNOME**  instead of a default window manager.
3379
3380
3381
3382   The easiest way to start  **GNOME**  is with  **GDM** , the GNOME Display Manager.  **GDM** , which is installed as a part of the  **GNOME**  desktop (but is disabled by default), can be enabled by adding `gdm_enable="YES"` to `/etc/rc.conf`. Once you have rebooted,  **GNOME**  will start automatically once you log in -- no further configuration is necessary.
3383
3384
3385
3386 **GNOME**  may also be started from the command-line by properly configuring a file named `.xinitrc`. If a custom `.xinitrc` is already in place, simply replace the line that starts the current window manager with one that starts  **/usr/pkg/bin/gnome-session**  instead. If nothing special has been done to the configuration file, then it is enough simply to type:
3387
3388
3389
3390       
3391
3392     % echo "/usr/pkg/bin/gnome-session" > ~/.xinitrc
3393
3394
3395
3396
3397
3398   Next, type `startx`, and the  **GNOME**  desktop environment will be started.
3399
3400
3401 **Note:** If an older display manager, like  **XDM** , is being used, this will not work. Instead, create an executable `.xsession` file with the same command in it. To do this, edit the file and replace the existing window manager command with  **/usr/pkg/bin/gnome-session** :
3402
3403
3404
3405         
3406
3407     % echo "#!/bin/sh" > ~/.xsession
3408
3409     % echo "/usr/pkg/bin/gnome-session" >> ~/.xsession
3410
3411     % chmod +x ~/.xsession
3412
3413
3414
3415
3416
3417   Yet another option is to configure the display manager to allow choosing the window manager at login time; the section on [ KDE details](x11-wm.html#X11-WM-KDE-DETAILS) explains how to do this for  **kdm** , the display manager of  **KDE** .
3418
3419
3420
3421 ### 5.7.1.3 Anti-aliased Fonts with GNOME 
3422
3423
3424
3425   X11 supports anti-aliasing via its ***RENDER*** extension. GTK+ 2.0 and greater (the toolkit used by  **GNOME** ) can make use of this functionality. Configuring anti-aliasing is described in [ Section 5.5.3](x-fonts.html#ANTIALIAS).
3426   
3427   So, with up-to-date software, anti-aliasing is possible within the  **GNOME**  desktop. Just go to  **Applications->Desktop Preferences->Font** , and select either Best shapes, Best contrast, or Subpixel smoothing (LCDs). For a GTK+ application that is not part of the  **GNOME**  desktop, set the environment variable `GDK_USE_XFT` to `1` before launching the program.
3428
3429
3430
3431 ## 5.7.2 KDE 
3432
3433
3434
3435 ### 5.7.2.1 About KDE 
3436
3437
3438
3439   **KDE**  is an easy to use contemporary desktop environment. Some of the things that  **KDE**  brings to the user are:
3440
3441 * A beautiful contemporary desktop
3442
3443 * A desktop exhibiting complete network transparency
3444
3445 * An integrated help system allowing for convenient, consistent access to help on the use of the  **KDE**  desktop and its applications
3446
3447 * Consistent look and feel of all  **KDE**  applications
3448
3449 * Standardized menu and toolbars, keybindings, color-schemes, etc.
3450
3451 * Internationalization:  **KDE**  is available in more than 40 languages
3452
3453 * Centralized consisted dialog driven desktop configuration
3454
3455 * A great number of useful  **KDE**  applications
3456
3457   **KDE**  comes with a web browser called  **Konqueror** , which represents a solid competitor to other existing web browsers on UNIX® systems. More information on  **KDE**  can be found on the [KDE website](http://www.kde.org/).
3458
3459
3460
3461 ### 5.7.2.2 Installing KDE 
3462
3463
3464  Just as with  **GNOME**  or any other desktop environment, the easiest way to install  **KDE**  is through the pkgsrc framework or from a package:
3465
3466
3467
3468  To install the  **KDE**  package from the network, simply type:
3469
3470    # pkg_radd kde3
3471
3472  or if you prefer the newer **KDE 4**, type:
3473  
3474    # pkg_radd kde4
3475
3476  [pkg_radd(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#pkg_radd&section1) will automatically fetch the latest version of the application.
3477
3478
3479  To build  **KDE**  from source, use the pkgsrc framework:
3480
3481     # cd /usr/pkgsrc/meta-pkgs/kde3
3482
3483     # bmake install clean
3484
3485
3486
3487
3488
3489  After  **KDE**  has been installed, the X server must be told to launch this application instead of the default window manager. This is accomplished by editing the `.xinitrc` file:
3490
3491
3492     % echo "exec startkde" > ~/.xinitrc
3493
3494
3495  Now, whenever the X Window System is invoked with `startx`,  **KDE**  will be the desktop.
3496
3497  If a display manager such as  **XDM**  is being used, the configuration is slightly different. Edit the `.xsession` file instead. Instructions for  **kdm**  are described later in this chapter.
3498
3499
3500
3501 ## 5.7.3 More Details on KDE 
3502
3503
3504
3505  Now that  **KDE**  is installed on the system, most things can be discovered through the help pages, or just by pointing and clicking at various menus. Windows® or Mac® users will feel quite at home.
3506
3507  The best reference for  **KDE**  is the on-line documentation.  **KDE**  comes with its own web browser,  **Konqueror** , dozens of useful applications, and extensive documentation. The remainder of this section discusses the technical items that are difficult to learn by random exploration.
3508
3509
3510
3511 ### 5.7.3.1 The KDE Display Manager 
3512
3513
3514
3515  An administrator of a multi-user system may wish to have a graphical login screen to welcome users. [ XDM](x-xdm.html) can be used, as described earlier. However,  **KDE**  includes an alternative,  **kdm** , which is designed to look more attractive and include more login-time options. In particular, users can easily choose (via a menu) which desktop environment ( **KDE** ,  **GNOME** , or something else) to run after logging on.
3516
3517
3518
3519  To enable  **kdm** , the `ttyv8` entry in `/etc/ttys` has to be adapted. The line should look as follows:
3520   
3521
3522     ttyv8 "/usr/pkg/bin/kdm -nodaemon" xterm on secure
3523
3524
3525     
3526 ## 5.7.4 XFce 
3527
3528
3529
3530 ### 5.7.4.1 About XFce 
3531
3532
3533   **XFce**  is a desktop environment based on the GTK+ toolkit used by  **GNOME** , but is much more lightweight and meant for those who want a simple, efficient desktop which is nevertheless easy to use and configure. Visually, it looks very much like  **CDE** , found on commercial UNIX systems. Some of  **XFce** 's features are:
3534
3535 * A simple, easy-to-handle desktop
3536
3537 * Fully configurable via mouse, with drag and drop, etc
3538
3539 * Main panel similar to  **CDE** , with menus, applets and applications launchers
3540
3541 * Integrated window manager, file manager, sound manager,  **GNOME**  compliance module, and other things
3542
3543 * Themeable (since it uses GTK+)
3544
3545 * Fast, light and efficient: ideal for older/slower machines or machines with memory limitations
3546
3547
3548 More information on  **XFce**  can be found on the [XFce website](http://www.xfce.org/).
3549
3550
3551
3552 ### 5.7.4.2 Installing XFce 
3553
3554
3555
3556  A binary package for  **XFce**  exists. To install, simply type:
3557
3558     # pkg_radd xfce4
3559
3560
3561  Alternatively, to build from source, use the pkgsrc framework:
3562
3563    
3564
3565     # cd /usr/pkgsrc/meta-pkgs/xfce4
3566
3567     # bmake install clean
3568
3569
3570
3571
3572  Now, tell the X server to launch  **XFce**  the next time X is started. Simply type this:
3573
3574     % echo "/usr/pkg/bin/startxfce4" > ~/.xinitrc
3575
3576
3577
3578  The next time X is started,  **XFce**  will be the desktop. As before, if a display manager like  **XDM**  is being used, create an `.xsession`, as described in the section on [ GNOME](x11-wm.html#X11-WM-GNOME), but with the `/usr/pkg/bin/startxfce4` command; or, configure the display manager to allow choosing a desktop at login time, as explained in the section on [ kdm](x11-wm.html#X11-WM-KDE-KDM).
3579
3580
3581
3582 <!-- XXX: FreeBSD's handbook has a nice user-oriented section about X applications here. maybe we should have one, too -->
3583
3584 ----
3585
3586
3587
3588
3589
3590
3591 <!-- XXX: break the stuff up here -->
3592
3593
3594 # II. System Administration 
3595
3596
3597
3598 The remaining chapters of the DragonFly Handbook cover all aspects of DragonFly system administration. Each chapter starts by describing what you will learn as a result of reading the chapter, and also details what you are expected to know before tackling the material. These chapters are designed to be read when you need the information. You do not have to read them in any particular order, nor do you need to read all of them before you can begin using DragonFly.
3599
3600
3601 ## Chapter 6 Configuration and Tuning 
3602
3603
3604 ***Written by Chern Lee.  Based on a tutorial written by Mike Smith.  Also based on [tuning(7)](http://leaf.dragonflybsd.org/cgi/web-man?command#tuning&section7) written by Matt Dillon.***
3605
3606
3607
3608 ## 6.1 Synopsis 
3609
3610
3611
3612 One of the important aspects of DragonFly is system configuration. Correct system configuration will help prevent headaches during future upgrades. This chapter will explain much of the DragonFly configuration process, including some of the parameters which can be set to tune a DragonFly system.
3613
3614
3615 After reading this chapter, you will know:
3616
3617 * How to efficiently work with file systems and swap partitions.
3618
3619 * The basics of `rc.conf` configuration and `rc.d` startup systems.
3620
3621 * How to configure and test a network card.
3622
3623 * How to configure virtual hosts on your network devices.
3624
3625 * How to use the various configuration files in `/etc`.
3626
3627 * How to tune DragonFly using `sysctl` variables.
3628
3629 * How to tune disk performance and modify kernel limitations.
3630
3631
3632 Before reading this chapter, you should:
3633
3634 * Understand UNIX® and DragonFly basics ([Chapter 3](basics.html)).
3635
3636 * Be familiar with the basics of kernel configuration/compilation ([Chapter 9](kernelconfig.html)).
3637
3638
3639
3640
3641
3642
3643
3644 CategoryHandbook
3645
3646 Category
3647
3648
3649
3650
3651
3652
3653
3654 ## 6.2 Initial Configuration 
3655
3656
3657 ### 6.2.1 Partition Layout 
3658
3659
3660 #### 6.2.1.1 Base Partitions 
3661
3662 When laying out file systems with [disklabel(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel&section=8) remember that hard drives transfer data faster from the outer tracks to the inner. Thus smaller and heavier-accessed file systems should be closer to the outside of the drive, while larger partitions like `/usr` should be placed toward the inner. It is a good idea to create partitions in a similar order to: root, swap, `/var`, `/usr`.
3663 <!-- XXX: on the advent of SSDs, do we really need to talk about this stuff? Who knows where on the platter the partitions land, considering that a hard disk has multiple platters? -->
3664
3665
3666
3667 The size of `/var` reflects the intended machine usage. `/var` is used to hold mailboxes, log files, and printer spools. Mailboxes and log files can grow to unexpected sizes depending on how many users exist and how long log files are kept. Most users would never require a gigabyte, but remember that `/var/tmp` must be large enough to contain packages.
3668
3669
3670
3671 The `/usr` partition holds much of the files required to support the system, the pkgsrc® collection (recommended) and the source code (optional). At least 2 gigabytes would be recommended for this partition.
3672
3673
3674
3675 When selecting partition sizes, keep the space requirements in mind. Running out of space in one partition while barely using another can be a hassle.
3676
3677
3678
3679 #### 6.2.1.2 Swap Partition 
3680
3681
3682
3683 As a rule of thumb, the swap partition should be about double the size of system memory (RAM). For example, if the machine has 128 megabytes of memory, the swap file should be 256 megabytes. Systems with less memory may perform better with more swap. Less than 256 megabytes of swap is not recommended and memory expansion should be considered. The kernel's VM paging algorithms are tuned to perform best when the swap partition is at least two times the size of main memory. Configuring too little swap can lead to inefficiencies in the VM page scanning code and might create issues later if more memory is added.
3684 <!-- XXX: do we really recommend double the RAM for swap? IMHO the amount of RAM should be more than enough -->
3685
3686
3687 On larger systems with multiple SCSI disks (or multiple IDE disks operating on different controllers), it is recommend that a swap is configured on each drive (up to four drives). The swap partitions should be approximately the same size. The kernel can handle arbitrary sizes but internal data structures scale to 4 times the largest swap partition. Keeping the swap partitions near the same size will allow the kernel to optimally stripe swap space across disks. Large swap sizes are fine, even if swap is not used much. It might be easier to recover from a runaway program before being forced to reboot.
3688
3689
3690
3691 #### 6.2.1.3 Why Partition? 
3692
3693
3694
3695 Several users think a single large partition will be fine, but there are several reasons why this is a bad idea. First, each partition has different operational characteristics and separating them allows the file system to tune accordingly. For example, the root and `/usr` partitions are read-mostly, without much writing. While a lot of reading and writing could occur in `/var` and `/var/tmp`.
3696
3697 By properly partitioning a system, fragmentation introduced in the smaller write heavy partitions will not bleed over into the mostly-read partitions. Keeping the write-loaded partitions closer to the disk's edge, will increase I/O performance in the partitions where it occurs the most. Now while I/O performance in the larger partitions may be needed, shifting them more toward the edge of the disk will not lead to a significant performance improvement over moving `/var` to the edge. Finally, there are safety concerns. A smaller, neater root partition which is mostly read-only has a greater chance of surviving a bad crash.
3698 <!-- XXX: again, same story about the edges of disks... -->
3699
3700
3701
3702 CategoryHandbook
3703
3704 CategoryHandbook-configuration
3705
3706
3707
3708
3709
3710 ## 6.3 Core Configuration 
3711
3712
3713
3714 The principal location for system configuration information is within `/etc/rc.conf`. This file contains a wide range of configuration information, principally used at system startup to configure the system. Its name directly implies this; it is configuration information for the `rc*` files.
3715
3716
3717
3718 An administrator should make entries in the `rc.conf` file to override the default settings from `/etc/defaults/rc.conf`. The defaults file should not be copied verbatim to `/etc` - it contains default values, not examples. All system-specific changes should be made in the `rc.conf` file itself.
3719
3720
3721
3722 A number of strategies may be applied in clustered applications to separate site-wide configuration from system-specific configuration in order to keep administration overhead down. The recommended approach is to place site-wide configuration into another file, such as `/etc/rc.conf.site`, and then include this file into `/etc/rc.conf`, which will contain only system-specific information.
3723
3724
3725
3726 As `rc.conf` is read by [sh(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=sh&section=1) it is trivial to achieve this. For example:
3727
3728 * rc.conf:
3729
3730         hostname="node15.example.com"
3731
3732         network_interfaces="fxp0 lo0"
3733
3734         ifconfig_fxp0="inet 10.1.1.1"
3735
3736   
3737
3738
3739 * rc.conf.site: 
3740
3741         defaultrouter="10.1.1.254"
3742
3743         saver="daemon"
3744
3745         blanktime="100"
3746
3747   
3748
3749
3750
3751 The `rc.conf.site` file can then be distributed to every system using `rsync` or a similar program, while the `rc.conf` file remains unique.
3752
3753
3754
3755 Upgrading the system using `make world` will not overwrite the `rc.conf` file, so system configuration information will not be lost.
3756
3757
3758 CategoryHandbook
3759
3760 CategoryHandbook-configuration
3761
3762
3763
3764
3765 ## Application Configuration 
3766
3767
3768
3769 Typically, installed applications have their own configuration files, with their own syntax, etc. It is important that these files be kept separate from the base system, so that they may be easily located and managed by the package management tools.
3770
3771
3772
3773 Typically, these files are installed in `/usr/pkg/etc`. In the case where an application has a large number of configuration files, a subdirectory will be created to hold them.
3774
3775
3776
3777 Normally, when a port or package is installed, sample configuration files are also installed. These are usually identified with a `.default` suffix. If there are no existing configuration files for the application, they will be created by copying the `.default` files.
3778
3779
3780
3781 For example, consider the contents of the directory `/usr/pkg/etc/httpd`:
3782
3783
3784
3785     
3786
3787     total 90
3788
3789     -rw-r--r--  1 root  wheel  -   34K Jan 11 12:04 httpd.conf
3790
3791     -rw-r--r--  1 root  wheel  -   13K Jan 11 12:02 magic
3792
3793     -rw-r--r--  1 root  wheel  -   28K Jan 11 12:02 mime.types
3794
3795     -rw-r--r--  1 root  wheel  -   11K Jan 11 12:02 ssl.conf
3796
3797
3798
3799
3800     
3801     
3802     
3803     
3804     
3805
3806 ## Starting Services 
3807
3808
3809
3810 It is common for a system to host a number of services. These may be started in several different fashions, each having different advantages.
3811
3812
3813
3814 Software installed from a port or the packages collection will often place a script in `/usr/pkg/share/examples/rc.d` which is invoked at system startup with a `start` argument, and at system shutdown with a `stop` argument. This is the recommended way for starting system-wide services that are to be run as `root`, or that expect to be started as `root`. These scripts are registered as part of the installation of the package, and will be removed when the package is removed.
3815
3816
3817 A generic startup script in `/usr/pkg/share/examples/rc.d` looks like:
3818
3819
3820
3821     
3822
3823     #!/bin/sh
3824
3825     echo -n ' FooBar'
3826
3827     
3828
3829     case "$1" in
3830
3831     start)
3832
3833             /usr/pkg/bin/foobar
3834
3835             ;;
3836
3837     stop)
3838
3839             kill -9 `cat /var/run/foobar.pid`
3840
3841             ;;
3842
3843     
3844 *)
3845
3846             echo "Usage: `basename $0` {start|stop}" >&2
3847
3848             exit 64
3849
3850             ;;
3851
3852     esac
3853
3854     
3855
3856     exit 0
3857
3858     
3859
3860
3861
3862
3863 <!-- XXX: I don't think we actually look in /usr/pkg/share/examples/rc.d -->
3864
3865 The startup scripts of DragonFly will look in `/usr/pkg/share/examples/rc.d` for scripts that have an `.sh` extension and are executable by `root`. Those scripts that are found are called with an option `start` at startup, and `stop` at shutdown to allow them to carry out their purpose. So if you wanted the above sample script to be picked up and run at the proper time during system startup, you should save it to a file called `FooBar.sh` in `/usr/local/etc/rc.d` and make sure it is executable. You can make a shell script executable with [chmod(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=chmod&section=1) as shown below:
3866
3867
3868
3869     
3870
3871     # chmod 755 "FooBar.sh"
3872
3873
3874
3875
3876
3877 Some services expect to be invoked by [inetd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=inetd&section=8) when a connection is received on a suitable port. This is common for mail reader servers (POP and IMAP, etc.). These services are enabled by editing the file `/etc/inetd.conf`. See [inetd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=inetd&section=8) for details on editing this file.
3878
3879
3880
3881 Some additional system services may not be covered by the toggles in `/etc/rc.conf`. These are traditionally enabled by placing the command(s) to invoke them in `/etc/rc.local` (which does not exist by default). Note that `rc.local` is generally regarded as the location of last resort; if there is a better place to start a service, do it there.
3882
3883
3884
3885  **Note:** Do ***not*** place any commands in `/etc/rc.conf`. To start daemons, or run any commands at boot time, place a script in `/usr/pkg/share/examples/rc.d` instead.
3886
3887
3888
3889 It is also possible to use the [cron(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=cron&section=8) daemon to start system services. This approach has a number of advantages, not least being that because [cron(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=cron&section=8) runs these processes as the owner of the `crontab`, services may be started and maintained by non-`root` users.
3890
3891
3892
3893 This takes advantage of a feature of [cron(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=cron&section=8): the time specification may be replaced by `@reboot`, which will cause the job to be run when [cron(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=cron&section=8) is started shortly after system boot.
3894
3895
3896
3897
3898
3899
3900
3901 CategoryHandbook
3902
3903 CategoryHandbook-configuration
3904
3905
3906
3907
3908
3909
3910
3911 ## Configuring the cron Utility 
3912
3913 <!-- XXX: can't really comment on this. someone please revise it -->
3914
3915
3916 ***Contributed by Tom Rhodes. ***
3917
3918
3919
3920 One of the most useful utilities in DragonFly is [cron(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=cron&section=8). The `cron` utility runs in the background and constantly checks the `/etc/crontab` file. The `cron` utility also checks the `/var/cron/tabs` directory, in search of new `crontab` files. These `crontab` files store information about specific functions which `cron` is supposed to perform at certain times.
3921
3922
3923
3924 The `cron` utility uses two different types of configuration files, the system crontab and user crontabs. The only difference between these two formats is the sixth field. In the system crontab, the sixth field is the name of a user for the command to run as. This gives the system crontab the ability to run commands as any user. In a user crontab, the sixth field is the command to run, and all commands run as the user who created the crontab; this is an important security feature.
3925
3926
3927
3928  **Note:** User crontabs allow individual users to schedule tasks without the need for root privileges. Commands in a user's crontab run with the permissions of the user who owns the crontab.
3929
3930
3931
3932 The `root` user can have a user crontab just like any other user. This one is different from `/etc/crontab` (the system crontab). Because of the system crontab, there's usually no need to create a user crontab for `root`.
3933
3934
3935
3936 Let us take a look at the `/etc/crontab` file (the system crontab):
3937
3938
3939
3940     
3941
3942     # /etc/crontab - root's crontab for DragonFly
3943
3944     #
3945
3946     #                                                                  (1)
3947
3948     #
3949
3950     SHELL=/bin/sh
3951
3952     PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin                            (2)
3953
3954     HOME=/var/log
3955
3956     #
3957
3958     #
3959
3960     #minute     hour    mday    month   wday    who     command            (3)
3961
3962     #
3963
3964     #
3965
3966     
3967     */5 *       *       *       *       root    /usr/libexec/atrun (4)
3968
3969
3970
3971
3972
3973  1. Like most DragonFly configuration files, the `#` character represents a comment. A comment can be placed in the file as a reminder of what and why a desired action is performed. Comments cannot be on the same line as a command or else they will be interpreted as part of the command; they must be on a new line. Blank lines are ignored.
3974
3975
3976
3977  1. First, the environment must be defined. The equals (`=`) character is used to define any environment settings, as with this example where it is used for the `SHELL`, `PATH`, and `HOME` options. If the shell line is omitted, `cron` will use the default, which is `sh`. If the `PATH` variable is omitted, no default will be used and file locations will need to be absolute. If `HOME` is omitted, `cron` will use the invoking users home directory.
3978
3979
3980
3981  1. This line defines a total of seven fields. Listed here are the values `minute`, `hour`, `mday`, `month`, `wday`, `who`, and `command`. These are almost all self explanatory. `minute` is the time in minutes the command will be run. `hour` is similar to the `minute` option, just in hours. `mday` stands for day of the month. `month` is similar to `hour` and `minute`, as it designates the month. The `wday` option stands for day of the week. All these fields must be numeric values, and follow the twenty-four hour clock. The `who` field is special, and only exists in the `/etc/crontab` file. This field specifies which user the command should be run as. When a user installs his or her `crontab` file, they will not have this option. Finally, the `command` option is listed. This is the last field, so naturally it should designate the command to be executed.
3982
3983
3984
3985  1. This last line will define the values discussed above. Notice here we have a `*/5` listing, followed by several more `*` characters. These `*` characters mean ***first-last***, and can be interpreted as ***every*** time. So, judging by this line, it is apparent that the `atrun` command is to be invoked by `root` every five minutes regardless of what day or month it is. For more information on the `atrun` command, see the [atrun(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=atrun&section=8) manual page.Commands can have any number of flags passed to them; however, commands which extend to multiple lines need to be broken with the backslash ***\*** continuation character.
3986
3987
3988
3989 This is the basic set up for every `crontab` file, although there is one thing different about this one. Field number six, where we specified the username, only exists in the system `/etc/crontab` file. This field should be omitted for individual user `crontab` files.
3990
3991
3992
3993 ### Installing a Crontab 
3994
3995
3996
3997  **Important:** You must not use the procedure described here to edit/install the system crontab. Simply use your favorite editor: the `cron` utility will notice that the file has changed and immediately begin using the updated version. If you use `crontab` to load the `/etc/crontab` file you may get an error like `root: not found` because of the system crontab's additional user field.
3998
3999
4000
4001 To install a freshly written user `crontab`, first use your favorite editor to create a file in the proper format, and then use the `crontab` utility. The most common usage is:
4002
4003
4004
4005     
4006
4007     % crontab crontab-file
4008
4009
4010
4011
4012
4013 In this example, `crontab-file` is the filename of a `crontab` that was previously created.
4014
4015
4016
4017 There is also an option to list installed `crontab` files: just pass the `-l` option to `crontab` and look over the output.
4018
4019
4020
4021 For users who wish to begin their own crontab file from scratch, without the use of a template, the `crontab -e` option is available. This will invoke the selected editor with an empty file. When the file is saved, it will be automatically installed by the `crontab` command.
4022
4023
4024
4025 If you later want to remove your user `crontab` completely, use `crontab` with the `-r` option.
4026
4027
4028
4029
4030
4031
4032
4033 CategoryHandbook
4034
4035 CategoryHandbook-configuration
4036
4037
4038
4039
4040
4041 ## 6.7 Using rc under DragonFly 
4042
4043
4044
4045 ***Contributed by Tom Rhodes. ***
4046
4047
4048
4049 DragonFly uses the NetBSD® `rc.d` system for system initialization. Users should notice the files listed in the `/etc/rc.d` directory. Many of these files are for basic services which can be controlled with the `start`, `stop`, and `restart` options. For instance, [sshd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=sshd&section=8&manpath=OpenBSD+3.3) can be restarted with the following command:
4050
4051
4052
4053     
4054
4055     # /etc/rc.d/sshd restart
4056
4057
4058
4059
4060
4061 This procedure is similar for other services. Of course, services are usually started automatically as specified in [rc.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=rc.conf&section=5). For example, enabling the Network Address Translation daemon at startup is as simple as adding the following line to `/etc/rc.conf`:
4062
4063
4064     natd_enable="YES"
4065
4066
4067
4068 If a `natd_enable="NO"` line is already present, then simply change the `NO` to `YES`. The rc scripts will automatically load any other dependent services during the next reboot, as described below.
4069
4070
4071 Another way to add services to the automatic startup/shutdown is to type, for example for `natd`,
4072
4073      # rcenable natd
4074
4075
4076 Since the `rc.d` system is primarily intended to start/stop services at system startup/shutdown time, the standard `start`, `stop` and `restart` options will only perform their action if the appropriate `/etc/rc.conf` variables are set. For instance the above `sshd restart` command will only work if `sshd_enable` is set to `YES` in `/etc/rc.conf`. To `start`, `stop` or `restart` a service regardless of the settings in `/etc/rc.conf`, the commands should be prefixed with ***force***. For instance to restart `sshd` regardless of the current `/etc/rc.conf` setting, execute the following command:
4077
4078
4079
4080     
4081
4082     # /etc/rc.d/sshd forcerestart
4083
4084
4085
4086
4087
4088 It is easy to check if a service is enabled in `/etc/rc.conf` by running the appropriate `rc.d` script with the option `rcvar`. Thus, an administrator can check that `sshd` is in fact enabled in `/etc/rc.conf` by running:
4089
4090
4091
4092     
4093
4094     # /etc/rc.d/sshd rcvar
4095
4096     # sshd
4097
4098     $sshd_enable=YES
4099
4100
4101
4102
4103
4104  **Note:** The second line (`# sshd`) is the output from the `rc.d` script, not a `root` prompt.
4105
4106
4107
4108 To determine if a service is running, a `status` option is available. For instance to verify that `sshd` is actually started:
4109
4110
4111
4112     
4113
4114     # /etc/rc.d/sshd status
4115
4116     sshd is running as pid 433.
4117
4118
4119
4120
4121
4122 It is also possible to `reload` a service. This will attempt to send a signal to an individual service, forcing the service to reload its configuration files. In most cases this means sending the service a `SIGHUP` signal.
4123
4124
4125
4126 The  **rcNG**  structure is used both for network services and system initialization. Some services are run only at boot; and the RCNG system is what triggers them.
4127
4128
4129
4130 Many system services depend on other services to function properly. For example, NIS and other RPC-based services may fail to start until after the `rpcbind` (portmapper) service has started. To resolve this issue, information about dependencies and other meta-data is included in the comments at the top of each startup script. The [rcorder(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rcorder&section=8) program is then used to parse these comments during system initialization to determine the order in which system services should be invoked to satisfy the dependencies. The following words may be included at the top of each startup file:
4131
4132
4133
4134
4135 * `PROVIDE`: Specifies the services this file provides.
4136
4137
4138 * `REQUIRE`: Lists services which are required for this service. This file will run ***after*** the specified services.
4139
4140
4141 * `BEFORE`: Lists services which depend on this service. This file will run ***before*** the specified services.
4142
4143
4144 * KEYWORD: When [rcorder(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rcorder&section=8) uses the `-k` option, then only the rc.d files matching this keyword are used. [(1)](#FTN.AEN4751) For example, when using `-k shutdown`, only the `rc.d` scripts defining the `shutdown` keyword are used.
4145
4146   With the `-s` option, [rcorder(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rcorder&section=8) will skip any `rc.d` script defining the corresponding keyword to skip. For example, scripts defining the `nostart` keyword are skipped at boot time.
4147
4148
4149
4150 By using this method, an administrator can easily control system services without the hassle of ***runlevels*** like some other UNIX® operating systems.
4151
4152
4153
4154 Additional information about the DragonFly `rc.d` system can be found in the [rc(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rc&section=8), [rc.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=rc.conf&section=5), and [rc.subr(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rc.subr&section=8) manual pages.
4155
4156 ### Using DragonFly's rcrun(8) 
4157
4158 Besides the methods described above DragonFly supports [rcrun(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rcrun&section=8) to control rc(8) scripts.  [rcrun(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rcrun&section=8) provides a number of command for controlling rc(8)
4159
4160 scripts.  The ***start***, ***forcestart***, ***faststart***, ***stop***, ***restart***, and ***rcvar*** commands are just passed to the scripts.  See rc(8) for more information on these commands.
4161
4162
4163
4164 The remaining commands are:
4165
4166
4167
4168 [[!table  data="""
4169   **disable**  | Sets the corresponding `_enable` variable in rc.conf(5) to ***NO*** and runs the stop command. 
4170   **enable**   | Sets the corresponding `_enable` variable in rc.conf(5) to ***YES*** and runs the start command. 
4171   **list**  | Shows the status of the specified scripts.  If no argument is specified, the status of all scripts is shown. |
4172
4173 """]]
4174
4175
4176 To enable the [dntpd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=dntpd&section=8) service, you can use:
4177
4178      # rcenable dntpd
4179      
4180  
4181
4182 To check if [dntpd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=dntpd&section=8) is running you can use the following command:
4183
4184     
4185
4186     # rclist dntpd
4187
4188     rcng_dntpd=stopped
4189
4190
4191
4192 To start [dntpd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=dntpd&section=8):
4193
4194
4195
4196     
4197
4198     # rcstart dntpd
4199
4200     Running /etc/rc.d/dntpd start
4201
4202     Starting dntpd.
4203
4204
4205
4206 Restart and stop works the same way:
4207
4208     
4209
4210     # rcrestart dntpd
4211
4212     Stopping dntpd.
4213
4214     Starting dntpd.
4215
4216     
4217
4218     # rcstop dntpd
4219
4220     Stopping dntpd.
4221
4222
4223
4224
4225
4226 If a service is not enabled in `/etc/rc.conf`, but you want it start anyway, execute the following:
4227
4228     
4229
4230     # rcforce dntpd
4231
4232     Running /etc/rc.d/dntpd forcestart
4233
4234     Starting dntpd.
4235
4236
4237
4238 #### Notes 
4239
4240
4241
4242 [[!table  data="""
4243 <tablestyle="width:100%"> [(1)](configtuning-rcng.html#AEN4751) | Previously this was used to define *BSD dependent features.
4244 | |
4245
4246 """]]
4247
4248
4249
4250
4251
4252
4253
4254 ## 6.8 Setting Up Network Interface Cards 
4255
4256
4257
4258 ***Contributed by Marc Fonvieille. ***
4259
4260
4261
4262 Nowadays we can not think about a computer without thinking about a network connection. Adding and configuring a network card is a common task for any DragonFly administrator.
4263
4264
4265
4266 ### 6.8.1 Locating the Correct Driver 
4267
4268
4269
4270 Before you begin, you should know the model of the card you have, the chip it uses, and whether it is a PCI or ISA card. DragonFly supports a wide variety of both PCI and ISA cards. Check the Hardware Compatibility List for your release to see if your card is supported.
4271
4272
4273
4274 Once you are sure your card is supported, you need to determine the proper driver for the card. The file `/usr/src/sys/i386/conf/LINT` will give you the list of network interfaces drivers with some information about the supported chipsets/cards. If you have doubts about which driver is the correct one, read the manual page of the driver. The manual page will give you more information about the supported hardware and even the possible problems that could occur.
4275
4276