newhandbook - add new installer images
[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 <img src="http://leaf.dragonflybsd.org/~alexh/images/2.png"/>
360 <!-- XXX: insert image 2.png -->
361
362
363 As you can see, it gives you the option of logging in as `root` to run the live CD and play around or logging in as `installer` to install DragonFly to your hard drive. 
364
365 Log in as `installer`. You will then see the following screen:
366
367 <img src="http://leaf.dragonflybsd.org/~alexh/images/3.png"/>
368 <!-- XXX: insert image 3.png -->
369
370
371
372 ## Set up Disk for Installation 
373
374 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:
375
376 <img src="http://leaf.dragonflybsd.org/~alexh/images/5.png"/>
377 <!-- XXX: insert image 5.png -->
378
379 If you have multiple disks installed, chose one where you want to install DragonFly.  We chose `ad0` here.
380
381 <img src="http://leaf.dragonflybsd.org/~alexh/images/6.png"/>
382 <!-- XXX: insert image 6.png -->
383
384 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.
385 <!-- XXX: mention stuf about UFS+HAMMER being the default setup, and why. -->
386
387 <img src="http://leaf.dragonflybsd.org/~alexh/images/8.png"/>
388 <!-- XXX: insert image 8.png -->
389
390 We select HAMMER and see now the following screen:
391
392 <img src="http://leaf.dragonflybsd.org/~alexh/images/9.png"/>
393 <!-- XXX: insert image 9.png -->
394
395 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.
396
397
398
399
400
401 ## Install to Disk 
402
403 The following steps show how DragonFly can be installed to your hard disk:
404
405 <img src="http://leaf.dragonflybsd.org/~alexh/images/10.png"/>
406 <!-- XXX: image 10.png -->
407
408 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:
409
410 <img src="http://leaf.dragonflybsd.org/~alexh/images/12.png"/>
411 <!-- XXX: image 12.png -->
412
413 Next, we are given an option to configure the system or reboot:
414
415 <img src="http://leaf.dragonflybsd.org/~alexh/images/13.png"/>
416 <!-- XXX: image 13.png -->
417
418
419
420
421
422 ## Set up your system 
423
424
425 The following menu of the installer allows you to configure your previously installed system.
426
427 <img src="http://leaf.dragonflybsd.org/~alexh/images/14.png"/>
428 <!-- XXX: image 14.png -->
429
430 This includes setting a password for your `root` account:
431
432 <img src="http://leaf.dragonflybsd.org/~alexh/images/15.png"/>
433 <!-- XXX: image 15.png -->
434
435 Be sure to select the correct keyboard map for your system, and configure a hostname.
436
437
438 ### Add a new user 
439
440 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:
441
442 <img src="http://leaf.dragonflybsd.org/~alexh/images/16.png"/>
443 <!-- XXX: image 16.png -->
444
445 ### Configure the Network 
446
447 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):
448
449 <img src="http://leaf.dragonflybsd.org/~alexh/images/17.png"/>
450 <!-- XXX: image 17.png -->
451
452 After finishing your configuration you can escape into a live shell or reboot the system into your installation.
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467 ## Chapter 3 UNIX Basics 
468
469 ***Rewritten by Chris Shumway. ***
470
471
472
473 ## 3.1 Synopsis 
474
475
476
477 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.
478
479
480
481 After reading this chapter, you will know:
482
483
484
485
486 * How to use the ***virtual consoles*** of DragonFly.
487
488
489 * How UNIX file permissions work along with understanding file flags in DragonFly.
490
491
492 * The default DragonFly file system layout.
493
494
495 * The DragonFly disk organization.
496
497
498 * How to mount and unmount file systems.
499
500
501 * What processes, daemons, and signals are.
502
503
504 * What a shell is, and how to change your default login environment.
505
506
507 * How to use basic text editors.
508
509
510 * What devices and device nodes are.
511
512
513 * What binary format is used under DragonFly.
514
515
516 * How to read manual pages for more information.
517
518
519
520
521
522
523
524 CategoryHandbook
525
526 Category
527
528 ## Virtual Consoles and Terminals 
529
530
531 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.
532
533 <!-- XXX: also mention vesa.ko and other modes for the vt, but maybe somewhere else -->
534
535 ### The Console 
536
537 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:
538
539
540     Additional ABI support:.
541     Starting cron.
542     Local package initialization:.
543     Additional TCP options:.
544     
545     Wed Feb 18 17:53:48 GMT 2009
546     
547     DragonFly/i386 (Amnesiac) (ttyv0)
548
549     login: 
550
551
552 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:
553
554
555     DragonFly/i386 (Amnesiac) (ttyv0)
556
557
558 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:
559
560
561     login:
562
563
564 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.
565
566
567 ### Logging into DragonFly 
568
569 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.
570
571 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: 
572
573     login:
574
575 For the sake of this example, let us assume that your username is `john`. Type `john` at this prompt and press  **Enter** . You should then be presented with a prompt to enter a <i>password</i>:
576     
577
578     login: john
579     Password:
580
581
582
583 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.
584
585 ### Multiple Consoles 
586
587 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.
588
589
590 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.
591
592
593 ### The /etc/ttys File 
594
595 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.
596
597
598 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`:
599     
600
601     # name  getty                           type    status          comments
602     #
603     ttyv0   "/usr/libexec/getty Pc"         cons25  on  secure
604     # Virtual terminals
605     ttyv1   "/usr/libexec/getty Pc"         cons25  on  secure
606     ttyv2   "/usr/libexec/getty Pc"         cons25  on  secure
607     ttyv3   "/usr/libexec/getty Pc"         cons25  on  secure
608     ttyv4   "/usr/libexec/getty Pc"         cons25  on  secure
609     ttyv5   "/usr/libexec/getty Pc"         cons25  on  secure
610     ttyv6   "/usr/libexec/getty Pc"         cons25  on  secure
611     ttyv7   "/usr/libexec/getty Pc"         cons25  on  secure
612     ttyv8   "/usr/pkg/xorg/bin/xdm -nodaemon"  xterm   off secure
613
614
615 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.
616
617
618
619 ### Single User Mode Console 
620
621 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`:
622
623     
624
625     # name  getty                           type    status          comments
626     #
627     # If console is marked "insecure", then init will ask for the root password
628     # when going to single-user mode.
629     console none                            unknown off secure
630
631
632
633
634
635  **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.
636
637
638
639 #### Notes 
640
641
642
643 [[!table  data="""
644 <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. 
645  [ (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. 
646  [ (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. |
647
648 """]]
649
650
651
652
653
654 CategoryHandbook
655
656 CategoryHandbook-basics
657
658
659
660 ## Permissions 
661
662 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.
663
664 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:
665
666
667
668 [[!table  data="""
669 |<tablestyle="width:100%"> Value | Permission | Directory Listing 
670 <tablestyle="width:100%"> 0 | No read, no write, no execute | `---` 
671  1 | No read, no write, execute | `--x` 
672  2 | No read, write, no execute | `-w-` 
673  3 | No read, write, execute | `-wx` 
674  4 | Read, no write, no execute | `r--` 
675  5 | Read, no write, execute | `r-x` 
676  6 | Read, write, no execute | `rw-` 
677  7 | Read, write, execute | `rwx` |
678
679 """]]
680
681 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:
682
683
684
685     % ls -l
686     total 530
687     -rw-r--r--  1 root  wheel     512 Sep  5 12:31 myfile
688     -rw-r--r--  1 root  wheel     512 Sep  5 12:31 otherfile
689     -rw-r--r--  1 root  wheel    7680 Sep  5 12:31 email.txt
690     ...
691
692 Here is how the first column of `ls -l` is broken up:    
693
694     -rw-r--r--
695
696 <!-- XXX: Check all these http:// links to see if they are broken -->
697
698 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.
699
700
701
702 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.
703
704
705
706 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).
707
708 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.
709
710
711
712 ### Symbolic Permissions 
713
714
715
716 ***Contributed by Tom Rhodes.***
717
718
719
720 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:
721
722
723
724 [[!table  data="""
725 <tablestyle="width:100%"> Option | Letter | Represents 
726 <tablestyle="width:100%"> (who) | u | User 
727  (who) | g | Group owner 
728  (who) | o | Other 
729  (who) | a | All (***world***) 
730  (action) | + | Adding permissions 
731  (action) | - | Removing permissions 
732  (action) | = | Explicitly set permissions 
733  (permissions) | r | Read 
734  (permissions) | w | Write 
735  (permissions) | x | Execute 
736  (permissions) | t | Sticky bit 
737  (permissions) | s | Set UID or GID |
738
739 """]]
740
741 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`:
742
743
744
745     
746
747     % chmod go=FILE
748
749
750
751
752
753 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:
754
755
756
757     
758
759     % chmod go-w,a+x FILE
760
761
762
763
764
765 ### DragonFly File Flags 
766
767
768
769 ***Contributed by Tom Rhodes.***
770
771
772
773 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:
774
775
776
777     
778
779     # chflags sunlink file1
780
781
782
783
784
785 And to disable the system undeletable flag, simply issue the previous command with ***no*** in front of the `sunlink`. Observe:
786
787
788
789     
790
791     # chflags nosunlink file1
792
793
794
795
796
797 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:
798
799
800
801     
802
803     # ls -lo file1
804
805
806
807
808
809 The output should look like the following:
810
811
812
813     
814
815     -rw-r--r--  1 trhodes  trhodes  sunlnk 0 Mar  1 05:54 file1
816
817
818
819
820
821 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.
822
823
824
825
826 ## Directory Structure 
827
828
829
830 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.
831
832
833
834 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).
835
836
837
838 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.
839
840
841
842 [[!table  data="""
843 <tablestyle="width:100%">Directory | Description 
844 <tablestyle="width:100%">  `/` | Root directory of the file system. 
845  `/bin/` | User utilities fundamental to both single-user and multi-user environments. 
846  `/boot/` | Programs and configuration files used during operating system bootstrap. 
847  `/boot/defaults/` | Default bootstrapping configuration files; see [loader.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=loader.conf&section5). 
848  `/dev/` | Device nodes; see [intro(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=intro&section4). 
849  `/etc/` | System configuration files and scripts. 
850  `/etc/defaults/` | Default system configuration files; see [rc(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rc&section8). 
851  `/etc/mail/` | Configuration files for mail transport agents such as [sendmail(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=sendmail&section8). 
852  `/etc/namedb/` | `named` configuration files; see [named(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=named&section8). 
853  `/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). 
854  `/etc/ppp/` | `ppp` configuration files; see [ppp(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=ppp&section8). 
855  `/mnt/` | Empty directory commonly used by system administrators as a temporary mount point. 
856  `/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). 
857  `/root/` | Home directory for the `root` account. 
858  `/sbin/` | System programs and administration utilities fundamental to both single-user and multi-user environments. 
859  `/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). 
860  `/usr/` | The majority of user utilities and applications. 
861  `/usr/bin/` | Common utilities, programming tools, and applications. 
862  `/usr/include/` | Standard C include files. 
863  `/usr/lib/` | Archive libraries. 
864  `/usr/libdata/` | Miscellaneous utility data files. 
865  `/usr/libexec/` | System daemons &amp; system utilities (executed by other programs). 
866  `/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`. 
867  `/usr/obj/` | Architecture-specific target tree produced by building the `/usr/src` tree. 
868  `/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`. 
869  `/usr/pkg/xorg/` | Xorg distribution executables, libraries, etc (optional). 
870  `/usr/pkgsrc` | The pkgsrc tree for installing packages (optional). 
871  `/usr/sbin/` | System daemons &amp; system utilities (executed by users). 
872  `/usr/share/` | Architecture-independent files. 
873  `/usr/src/` | BSD and/or local source files. 
874  `/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). 
875  `/var/log/` | Miscellaneous system log files. 
876  `/var/mail/` | User mailbox files. 
877  `/var/spool/` | Miscellaneous printer and mail system spooling directories. 
878  `/var/tmp/` | Temporary files. The files are usually preserved across a system reboot, unless `/var` is a memory-based file system. 
879  `/var/yp` | NIS maps. |
880
881 """]]
882
883
884
885
886 ## Disk Organization 
887
888
889
890 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.
891
892
893
894 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.
895
896
897
898 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`.
899
900
901
902 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.
903
904
905
906 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 `\`.
907
908
909 DragonFly does not use drive letters, or other drive names in the path. You would not write `c:/foo/bar/readme.txt` on DragonFly.
910
911
912
913 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.
914
915
916
917 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`).
918
919
920
921 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:
922
923
924 <!-- XXX: image -->
925
926
927
928 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:
929
930
931
932 <!-- XXX: image -->
933
934
935 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.
936
937
938
939 If `B` had been mounted on `A2` then the diagram would look like this:
940
941
942 <!-- XXX: image -->
943
944
945
946 and the paths would be `/A2/B1` and `/A2/B2` respectively.
947
948
949
950 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:
951
952
953 <!-- XXX: image -->
954
955
956
957 Or `C` could be mounted directly on to the `A` file system, under the `A1` directory:
958
959
960 <!-- XXX: image -->
961
962
963
964 If you are familiar with MS-DOS, this is similar, although not identical, to the `join` command.
965
966
967
968
969
970 ### Choosing File System Layout 
971
972
973
974 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.
975
976
977
978 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.
979
980
981
982  **Benefits of Multiple File Systems** 
983
984
985
986
987 * 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.
988
989
990 * 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.
991
992
993 * 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.
994
995
996
997  **Benefit of a Single File System** 
998
999
1000
1001
1002 * 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.
1003 <!-- XXX: what about hammer? -->
1004
1005
1006
1007
1008 ### Disk Slices, Partitions and local UNIX file systems 
1009
1010 Here we describe how disks are subdivided.
1011
1012 <!-- XXX: mention serno stuff -->
1013
1014 #### Slices 
1015
1016 A disk can be subdivided in slices.
1017
1018 Slices are named `s0`, `s1` and so on.
1019
1020 For example the disk `ad6` can contain the slice `ad6s3`.
1021
1022 DragonFly support two schemes for slices, MBR and GPT, either of them will manage all slices on a disk:
1023
1024
1025 * 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.
1026
1027
1028 * 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).
1029
1030
1031
1032 #### Partitions 
1033
1034 Partitions are contained in slices.
1035
1036 Partitions are named `a`, `b` and so on.
1037
1038 DragonFly support 16 partitions per slice, that is `a` through `p`.
1039
1040 For example the partition `ad6s3a` is contained in the slice `ad6s3`.
1041
1042 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):
1043
1044
1045 * [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.
1046
1047
1048 * [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.
1049
1050
1051 #### Local UNIX file systems 
1052
1053 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.
1054
1055
1056
1057 DragonFly support two local UNIX file systems, UFS and HAMMER:
1058
1059
1060 * 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.
1061
1062
1063 * [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.
1064
1065
1066
1067 #### Typical disk layout 
1068
1069 From the above we see the following typical disk layout scenarios:
1070
1071
1072 * 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.
1073
1074
1075 * 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.
1076
1077
1078 * 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).
1079
1080
1081
1082
1083
1084 #### HAMMER Note 
1085
1086 [HAMMER(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=HAMMER&amp;section5)
1087
1088 is a rather new file system, under active development.
1089
1090 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 .
1091
1092 All major features except the mirroring are quite well tested as-of the 2.2.1 release.
1093
1094 You should evaluate if HAMMER is suitable for your needs.
1095 <!-- XXX: mention disk and memory requirements for efficient hammer use -->
1096
1097
1098 Examples of ongoing development includes:
1099
1100
1101 * 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).
1102
1103
1104 * Multi master mirroring. For now only one mirror master is supported, but multiple mirror targets, called slaves, are already supported.
1105
1106
1107 * Support for shrinking existing HAMMER file systems.  The HAMMER design is prepared for this, utility just have to be written to support it.
1108 <!-- XXX: is this still accurate? Do we really want to mention it here? -->
1109
1110
1111 #### HAMMER Features 
1112
1113 [HAMMER(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=HAMMER&amp;section5) has several advanced features not found in UFS:
1114
1115
1116 * Large file systems:  Up to 1 million TB, also called 1 Exabyte is supported.
1117
1118
1119 * 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.
1120
1121
1122 * 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.
1123
1124
1125 * 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.
1126
1127
1128 * 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). 
1129
1130
1131 * 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.
1132
1133
1134 * 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.
1135
1136
1137
1138 More info on HAMMER can be found [here](http://www.dragonflybsd.org/hammer/index.shtml).
1139
1140
1141
1142 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.
1143
1144 <!-- XXX: mention swapcache, and also how to configure and use it (somewhere else, probably) -->
1145
1146
1147
1148 ### Adding a Disk 
1149
1150
1151
1152 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.
1153
1154
1155
1156 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 
1157 [disklabel64(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel64&amp;section8).
1158
1159 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).
1160
1161
1162 <!-- XXX: mention that disklabel64 is default now -->
1163     
1164
1165     # gpt -v create ad6
1166
1167     ...
1168
1169     # gpt add -s1 ad6
1170
1171     ad6s0
1172
1173     # gpt add ad6
1174
1175     ad6s1
1176
1177     # gpt show ad6
1178
1179     ...
1180
1181
1182
1183
1184
1185 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.
1186
1187
1188
1189     
1190
1191     # disklabel64 -rw ad6s1 auto
1192
1193     # disklabel64 -e ad6s1          # edit label to add partitions as needed
1194
1195
1196
1197
1198
1199 ### disklabel 
1200 <!-- XXX: what is all this fuzz about dangerously dedicated? -->
1201
1202
1203 For [disklabel(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel&amp;section8) labels some partitions have certain conventions associated with them.
1204
1205
1206
1207 [[!table  data="""
1208 <tablestyle="width:100%"> Partition | Convention 
1209 <tablestyle="width:100%"> `a` | Normally contains the root file system 
1210  `b` | Normally contains swap space 
1211  `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.
1212  `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`. |
1213
1214 """]]
1215
1216 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.
1217
1218
1219
1220 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.
1221
1222 <!-- XXX: gpt allows for way more than 4 partitions... let's remove this stuff above -->
1223
1224 ***Dangerously dedicated*** physical drives are accessed as slice 0.
1225
1226
1227
1228 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.
1229
1230
1231
1232 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).
1233
1234 <!-- XXX: here would probably be the right place to talk about serno -->
1235
1236 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).
1237
1238 <!-- XXX: later talk also about devfs, definitely not here though. also, devfs rules -->
1239
1240 [Example 3-2](disk-organization.html#BASICS-CONCEPT-DISK-MODEL) shows a conceptual model of the disk layout that should help make things clearer.
1241
1242
1243
1244 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.
1245
1246
1247
1248 ***'Table 3-1. Disk Device Codes***'
1249
1250
1251
1252 [[!table  data="""
1253 <tablestyle="width:100%"> Code | Meaning 
1254 <tablestyle="width:100%"> `ad` | ATAPI (IDE) disk 
1255  `da` | SCSI direct access disk 
1256  `acd` | ATAPI (IDE) CDROM 
1257  `cd` | SCSI CDROM 
1258  `vn` | Virtual disk
1259  `fd` | Floppy disk |
1260
1261 """]]
1262
1263 ***'Example 3-1. Sample Disk, Slice, and Partition Names***'
1264
1265
1266
1267 [[!table  data="""
1268 <tablestyle="width:100%"> Name | Meaning 
1269 <tablestyle="width:100%"> `ad0s1a` | The first partition (`a`) on the first slice (`s1`) on the first IDE disk (`ad0`). 
1270  `da1s2e` | The fifth partition (`e`) on the second slice (`s2`) on the second SCSI disk (`da1`). |
1271
1272 """]]
1273
1274 ***'Example 3-2. Conceptual Model of a Disk***'
1275
1276
1277
1278 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.
1279
1280
1281
1282 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.
1283
1284
1285 <!-- XXX: image -->
1286
1287
1288
1289
1290
1291
1292 CategoryHandbook
1293
1294 CategoryHandbook-basics
1295
1296
1297
1298
1299
1300
1301
1302 ## Mounting and Unmounting File Systems 
1303
1304
1305
1306 The file system is best visualized as a tree, rooted at `/`.
1307
1308 The directories, e.g. `/dev` and `/usr`, in the root directory are branches,
1309
1310 which may have their own branches, such as `/usr/local`, and so on.
1311
1312
1313
1314 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.
1315
1316
1317
1318 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.
1319
1320
1321
1322
1323
1324 ### The fstab File 
1325
1326
1327
1328 During the [boot process](boot.html), file systems listed in `/etc/fstab` are automatically mounted (unless they are listed with the `noauto` option).
1329
1330
1331
1332 The `/etc/fstab` file contains a list of lines of the following format:
1333   
1334
1335     device       mount-point   fstype     options      dumpfreq     passno
1336
1337 These parameters have the following meaning:
1338
1339 * `device`: A device name (which should exist), as explained [here](disks-naming.html).
1340
1341 * `mount-point`: A directory (which should exist), on which to mount the file system.
1342
1343 * `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`.
1344
1345 * `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.
1346
1347 * `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.
1348
1349 * `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.
1350
1351
1352 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.
1353
1354
1355
1356
1357
1358 ### The mount Command 
1359
1360
1361
1362 The [mount(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=mount&section8) command is what is ultimately used to mount file systems.
1363
1364
1365
1366 In its most basic form, you use:
1367
1368
1369
1370     
1371
1372     # mount device mountpoint
1373
1374
1375
1376
1377
1378 Or, if `mountpoint` is specified in `/etc/fstab`, just:
1379
1380
1381
1382     
1383
1384     # mount mountpoint
1385
1386
1387
1388
1389
1390 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:
1391
1392
1393
1394  **Mount Options** 
1395
1396
1397
1398
1399 * `-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.
1400
1401
1402 * `-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.
1403
1404
1405 * `-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.
1406
1407
1408 * `-r`: Mount the file system read-only. This is identical to using the `rdonly` argument to the `-o` option.
1409
1410
1411 * `-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.
1412
1413
1414 * `-u`: Update mount options on the file system.
1415
1416
1417 * `-v`: Be verbose.
1418
1419
1420 * `-w`: Mount the file system read-write.
1421
1422
1423
1424 The `-o` option takes a comma-separated list of the options, including the following:
1425
1426
1427
1428
1429 * `nodev:` Do not interpret special devices on the file system. This is a useful security option.
1430
1431
1432 * `noexec`: Do not allow execution of binaries on this file system. This is also a useful security option.
1433
1434
1435 * `nosuid`: Do not interpret setuid or setgid flags on the file system. This is also a useful security option.
1436
1437
1438
1439 ### The umount Command 
1440
1441
1442
1443 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.
1444
1445
1446
1447 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.
1448
1449
1450
1451 `-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.
1452
1453
1454
1455
1456
1457
1458
1459 CategoryHandbook
1460
1461 CategoryHandbook-basics
1462
1463
1464
1465
1466
1467
1468 ## Processes 
1469
1470
1471
1472 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.
1473
1474 <!-- XXX: talk about LWPs and threads? -->
1475
1476 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.
1477
1478 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.
1479
1480
1481
1482 By default, `ps` only shows you the commands that are running and are owned by you. For example:
1483
1484
1485
1486     
1487
1488     % ps
1489
1490       PID  TT  STAT      TIME COMMAND
1491       298  p0  Ss     0:01.10 tcsh
1492      7078  p0  S      2:40.88 xemacs mdoc.xsl (xemacs-21.1.14)
1493     37393  p0  I      0:03.11 xemacs freebsd.dsl (xemacs-21.1.14)
1494     48630  p0  S      2:50.89 /usr/local/lib/netscape-linux/navigator-linux-4.77.bi
1495     48730  p0  IW     0:00.00 (dns helper) (navigator-linux-)
1496     72210  p0  R+     0:00.00 ps
1497       390  p1  Is     0:01.14 tcsh
1498      7059  p2  Is+    1:36.18 /usr/local/bin/mutt -y
1499      6688  p3  IWs    0:00.00 tcsh
1500     10735  p4  IWs    0:00.00 tcsh
1501     20256  p5  IWs    0:00.00 tcsh
1502       262  v0  IWs    0:00.00 -tcsh (tcsh)
1503       270  v0  IW+    0:00.00 /bin/sh /usr/X11R6/bin/startx -- -bpp 16
1504       280  v0  IW+    0:00.00 xinit /home/nik/.xinitrc -- -bpp 16
1505       284  v0  IW     0:00.00 /bin/sh /home/nik/.xinitrc
1506       285  v0  S      0:38.45 /usr/X11R6/bin/sawfish
1507
1508
1509
1510 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.
1511
1512
1513
1514 [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.
1515
1516
1517
1518 The output from [top(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=top&section1) is similar. A sample session looks like this:
1519
1520
1521
1522     
1523
1524     % top
1525     last pid: 72257;  load averages:  0.13,  0.09,  0.03    up 0+13:38:33  22:39:10
1526     47 processes:  1 running, 46 sleeping
1527     CPU states: 12.6% user,  0.0% nice,  7.8% system,  0.0% interrupt, 79.7% idle
1528     Mem: 36M Active, 5256K Inact, 13M Wired, 6312K Cache, 15M Buf, 408K Free
1529     Swap: 256M Total, 38M Used, 217M Free, 15% Inuse
1530     
1531
1532       PID USERNAME PRI NICE  SIZE    RES STATE    TIME   WCPU    CPU COMMAND
1533     72257 nik       28   0  1960K  1044K RUN      0:00 14.86%  1.42% top
1534      7078 nik        2   0 15280K 10960K select   2:54  0.88%  0.88% xemacs-21.1.14
1535       281 nik        2   0 18636K  7112K select   5:36  0.73%  0.73% XF86_SVGA
1536       296 nik        2   0  3240K  1644K select   0:12  0.05%  0.05% xterm
1537     48630 nik        2   0 29816K  9148K select   3:18  0.00%  0.00% navigator-linu
1538       175 root       2   0   924K   252K select   1:41  0.00%  0.00% syslogd
1539      7059 nik        2   0  7260K  4644K poll     1:38  0.00%  0.00% mutt
1540     ...
1541
1542 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.
1543
1544 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.
1545
1546
1547
1548 [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.
1549
1550
1551
1552
1553
1554 ## Daemons, Signals, and Killing Processes 
1555
1556
1557
1558 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.
1559
1560
1561
1562 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.
1563
1564
1565
1566 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.
1567
1568
1569
1570 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.
1571
1572
1573
1574 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.
1575
1576
1577
1578 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.
1579
1580
1581
1582 `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).
1583
1584
1585
1586 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.
1587
1588
1589
1590 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.
1591
1592
1593
1594 Signals are sent using the [kill(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=kill&section=1) command, as this example shows.
1595
1596
1597
1598  **Sending a Signal to a Process** 
1599
1600
1601
1602 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`.
1603
1604
1605
1606   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).
1607
1608       
1609
1610         % ps -ax | grep inetd
1611
1612         198  ??  IWs    0:00.00 inetd -wW
1613
1614   
1615
1616   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.
1617
1618   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.
1619
1620       
1621
1622         % su
1623
1624         Password:
1625
1626         # /bin/kill -s HUP 198
1627
1628   
1629
1630   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`.
1631
1632
1633
1634 **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.
1635
1636
1637
1638 Sending other signals is very similar, just substitute `TERM` or `KILL` in the command line as necessary.
1639
1640
1641
1642  **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** .
1643
1644  
1645  
1646  
1647  
1648  
1649 ## Shells 
1650
1651
1652
1653 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`.
1654
1655
1656
1657 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.
1658
1659
1660
1661 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** ]`.
1662
1663
1664
1665 The shell would print out `rm foo[BEEP].bar`.
1666
1667
1668
1669 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.
1670
1671
1672
1673 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:
1674
1675
1676
1677 [[!table  data="""
1678 <tablestyle="width:100%"> Variable | Description 
1679 <tablestyle="width:100%"> `USER` | Current logged in user's name. 
1680  `PATH` | Colon separated list of directories to search for binaries. 
1681  `DISPLAY` | Network name of the X11 display to connect to, if available. 
1682  `SHELL` | The current shell. 
1683  `TERM` | The name of the user's terminal. Used to determine the capabilities of the terminal. 
1684  `TERMCAP` | Database entry of the terminal escape codes to perform various terminal functions. 
1685  `OSTYPE` | Type of operating system. e.g., DragonFly. 
1686  `MACHTYPE` | The CPU architecture that the system is running on. 
1687  `EDITOR` | The user's preferred text editor. 
1688  `PAGER` | The user's preferred text pager. 
1689  `MANPATH` | Colon separated list of directories to search for manual pages. |
1690
1691 """]]
1692
1693 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`:
1694     
1695
1696     % setenv EDITOR /usr/pkg/bin/emacs
1697
1698
1699 Under Bourne shells:
1700    
1701
1702     % export EDITOR="/usr/pkg/bin/emacs"
1703
1704
1705
1706 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`.
1707
1708
1709
1710 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.
1711
1712
1713
1714 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.
1715
1716
1717
1718
1719 ### Changing Your Shell 
1720
1721 <!-- XXX: does chsh still exist? chpass will do, too -->
1722
1723 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.
1724
1725
1726 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:
1727
1728     
1729
1730     % chsh -s /usr/pkg/bin/bash
1731
1732
1733
1734
1735
1736  **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.
1737
1738
1739
1740 For example, if you installed `bash` by hand and placed it into `/usr/local/bin`, you would want to:
1741
1742
1743
1744     
1745
1746     # echo "/usr/local/bin/bash" >> /etc/shells
1747
1748
1749
1750
1751
1752 Then rerun `chsh`.
1753
1754
1755
1756
1757
1758
1759 ## Text Editors 
1760
1761
1762
1763 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.
1764
1765 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.
1766
1767 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.
1768
1769
1770
1771
1772 ## Devices and Device Nodes 
1773
1774 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`.
1775
1776 For example, `acd0` is the first IDE CDROM drive, while `kbd0` represents the keyboard.
1777
1778 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.
1779
1780 The device nodes in the `/dev` directory are created and destroyed automatically on DragonFly >= 2.4, by means of the device file system (devfs).
1781
1782
1783
1784 ## Binary Formats 
1785
1786
1787
1788 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®:
1789
1790
1791
1792
1793 * [a.out(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=a.out&amp;section=5)
1794
1795   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.
1796
1797
1798 * <u>COFF</u>
1799
1800   The SVR3 object format. The header now comprises a section table, so you can have more than just .text, .data, and .bss sections.
1801
1802
1803 * [elf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=elf&amp;section=5)
1804
1805   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.
1806
1807
1808
1809 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.
1810
1811 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.
1812
1813 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.
1814
1815 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.
1816
1817
1818
1819 <!-- XXX: do we really need all this bullshit about file formats? -->
1820
1821
1822 ## For More Information 
1823
1824 ### Manual Pages 
1825
1826 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:
1827
1828     % man command
1829
1830 `command` is the name of the command you wish to learn about. For example, to learn more about `ls` command type:
1831
1832     % man ls
1833
1834 The online manual is divided up into numbered sections:
1835
1836
1837   1. User commands.
1838   1. System calls and error numbers.
1839   1. Functions in the C libraries.
1840   1. Device drivers.
1841   1. File formats.
1842   1. Games and other diversions.
1843   1. Miscellaneous information.
1844   1. System maintenance and operation commands.
1845   1. Kernel internals.
1846
1847
1848
1849 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:
1850     
1851
1852     % man 1 chmod
1853
1854
1855 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.
1856
1857 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:
1858
1859    
1860
1861     % man -k mail
1862
1863
1864 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.
1865
1866 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:    
1867
1868     % cd /usr/bin
1869     % man -f *
1870
1871 or
1872    
1873
1874     % cd /usr/bin
1875     % whatis *
1876
1877 which does the same thing.
1878
1879
1880
1881 ### GNU Info Files 
1882
1883 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:
1884
1885
1886     % info
1887
1888 For a brief introduction, type `h`. For a quick command reference, type `?`.
1889
1890
1891
1892
1893
1894 ## Chapter 4 Installing Applications using NetBSD's pkgsrc framework 
1895
1896
1897 <!-- XXX: possibly also mention pkgin and other fancy stuff. Or at least pkg_radd if it's not mentioned already -->
1898
1899
1900
1901 ## Overview of Software Installation 
1902
1903 If you have used a UNIX® system before you will know that the typical procedure for installing third party software goes something like this:
1904
1905
1906   1. Download the software, which might be distributed in source code format, or as a binary.
1907
1908   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)).
1909
1910   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.
1911
1912   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.
1913
1914   1. Test and install the software.
1915
1916
1917 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.
1918
1919
1920 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.
1921
1922
1923
1924 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.
1925
1926
1927 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.
1928
1929
1930
1931  **Binary Package Benefits** 
1932
1933
1934
1935
1936 * A compressed package tarball is typically smaller than the compressed tarball containing the source code for the application.
1937
1938
1939 * 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.
1940
1941
1942 * Packages do not require any understanding of the process involved in compiling software on DragonFly.
1943
1944
1945
1946 **Pkgsrc source Benefits** 
1947
1948
1949
1950
1951 * 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.
1952
1953
1954 * 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.
1955
1956
1957 * The licensing conditions of some software distributions forbid binary distribution. They must be distributed as source code.
1958
1959
1960 * 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.
1961
1962
1963 * If you have local patches, you will need the source in order to apply them.
1964
1965
1966 * 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.
1967
1968
1969
1970 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.
1971
1972
1973
1974  **Warning:** Before installing any application, you should check http://www.pkgsrc.org/ for security issues related to your application.
1975
1976
1977
1978 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.
1979
1980
1981
1982
1983 ## Finding Your Application 
1984
1985
1986
1987 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:
1988
1989 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.
1990
1991  **Example. Find a Package** 
1992
1993     # pkg_search fvwm
1994     fvwm-2.4.20nb1          Newer version of X11 Virtual window manager
1995     fvwm-2.5.24             Development version of X11 Virtual window manager
1996     fvwm-themes-0.6.2nb8    Configuration framework for fvwm2 with samples
1997     fvwm-wharf-1.0nb1       Copy of AfterStep's Wharf compatible with fvwm2
1998     fvwm1-1.24rnb1          Virtual window manager for X
1999
2000     
2001
2002     # pkg_search -v fvwm-2.5
2003     Name    : fvwm-2.5.24-50
2004     Dir     : wm/fvwm-devel                                     
2005     Desc    : Development version of X11 Virtual window manager 
2006     URL     : any                                               
2007     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 
2008     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 
2009     libSM>=0.99.2 libICE>=0.99.1 png>=1.2.9nb2
2010
2011
2012 To get more verbose information about a package (dependencies, path in `/usr/pkgsrc`, Description) use the `-v` switch.
2013
2014 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.
2015
2016 ## Get the description of a package 
2017
2018 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):
2019
2020     # pkg_search -s fvwm-2.5.24
2021     Fvwm is a very famous window manager for X, which provides a
2022     virtual/multiple disjoint desktop, a 3-D look for windows decorations,
2023     shaped/color icons. It gives a very good emulation of mwm. A nice
2024     button-bar can be used to provide convenient access to frequently used
2025     functions or programs.
2026
2027     This package is based on the unstable 2.5.x series of fvwm.  Do not
2028     use it unless comfortable running beta software.
2029
2030
2031  **Note:**  To use the `-s` switch you need a complete pkgsrc tree installed.
2032
2033
2034  
2035  ## Using the Binary Packages System 
2036
2037
2038
2039 ***DragonFly customizations contributed by Chern Lee and Adrian Nida. ***
2040
2041
2042
2043 ### Installing a Binary Package 
2044
2045 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.
2046
2047 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.
2048
2049 <!-- XXX: put in pkg_radd example, it's more meaningful; also check the url below (ftp.pkgsrc-box.org) -->
2050
2051
2052 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.
2053
2054
2055
2056 The directory structure of the binary package system matches the source tree layout; they work with each other to form the entire package system.
2057
2058 #### Using pkg_radd 
2059
2060 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:
2061
2062     
2063
2064     # pkg_radd host
2065     #
2066
2067
2068 ### Dealing with different package versions 
2069
2070 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:
2071
2072     pkg_add: Warning: package `vim-gtk2-7.1.116.tgz' was built for a different version of the OS:
2073     pkg_add: DragonFly/i386 1.10.1 (pkg) vs. DragonFly/i386 1.11.0 (this host)
2074
2075 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.
2076
2077 ### Managing Packages 
2078
2079 [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.
2080
2081
2082
2083     # pkg_info
2084     digest-20050731     Message digest wrapper utility
2085     screen-4.0.2nb4     Multi-screen window manager
2086     ...
2087
2088 [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.
2089
2090 ### Deleting a Package 
2091
2092 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.
2093
2094
2095     # pkg_delete screen-4.0.3.tgz
2096
2097 ### Miscellaneous 
2098
2099 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.
2100
2101
2102
2103 ## Using the pkgsrc® Source Tree 
2104
2105 The following sections provide basic instructions on using the pkgsrc source tree to install or remove programs from your system.
2106
2107 ### Obtaining the pkgsrc Source Tree 
2108
2109 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`.
2110
2111 #### CVS 
2112
2113 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** .
2114
2115 Run `cvs`:
2116
2117     # cd /usr
2118     # cvs -d anoncvs@anoncvs.us.netbsd.org:/cvsroot co pkgsrc
2119
2120  
2121 Running the following command later will download and apply all the recent changes to your source tree.
2122
2123     # cd /usr/pkgsrc
2124     # cvs up
2125
2126   
2127 #### The DragonFly Way 
2128
2129 <!-- XXX: mention our git repo of pkgsrc -->
2130
2131
2132 As of the 1.10 release, you can use the `/usr/Makefile` to checkout & update the pkgsrc tree quickly.
2133
2134 as root:
2135
2136
2137     # cd /usr
2138     # make pkgsrc-create
2139
2140 to checkout from git repository, or
2141
2142
2143     # cd /usr
2144     # make pkgsrc-update
2145
2146 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.
2147
2148 ### Installing Packages from Source
2149
2150 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:
2151
2152 * A `Makefile`. The `Makefile` contains various statements that specify how the application should be compiled and where it should be installed on your system.
2153
2154
2155 * 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).
2156
2157
2158 * A `files` directory. This directory contains the application specific files that are needed for the programs appropriate run-time configuration.
2159
2160   This directory may also contain other files used to build the port.
2161
2162
2163 * 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.
2164
2165
2166 * A `DESCR` file. This is a more detailed, often multiple-line, description of the program.
2167
2168
2169 * 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.
2170
2171
2172
2173 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/).
2174
2175
2176
2177 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. 
2178
2179 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`:
2180
2181
2182     # cd /usr/pkgsrc
2183     # bmake search key="apache2"
2184     Extracting complete dependency database.  This may take a while...
2185     ....................................................................................................
2186     100
2187     ....................................................................................................
2188     200
2189     <Snip />
2190     5800
2191     ....................................................................................................
2192     5900
2193     .................................................................................................Reading database file
2194     Flattening dependencies
2195     Flattening build dependencies
2196     Generating INDEX file
2197     Indexed 5999 packages
2198     <Snip />
2199     Pkg:    apache-2.2.6nb2
2200     Path:   www/apache22
2201     Info:   Apache HTTP (Web) server, version 2
2202     Maint:  tron@NetBSD.org
2203     Index:  www
2204     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 
2205     {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
2206     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
2207     Arch:   any
2208
2209
2210 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.
2211
2212 The search string is case-insensitive. Searching for <i>APACHE</i> will yield the same results as searching for <i>apache</i>.
2213
2214
2215
2216  **Note:** It should be noted that <i>Extracting [the] complete dependency database</i> does indeed take a while.
2217
2218
2219
2220  **Note:** You must be logged in as `root` to install packages.
2221
2222
2223
2224 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.
2225
2226
2227
2228  **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.
2229
2230
2231 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.
2232
2233
2234
2235  **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.
2236
2237
2238
2239  **Note:** You can save an extra step by just running `bmake install` instead of `bmake` and `bmake install` as two separate steps.
2240
2241
2242
2243  **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)).
2244
2245 <!-- XXX: mention the stuff about the pkgsrc security audit thingie -->
2246
2247 #### Installing Packages from the Internet 
2248
2249
2250
2251 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.
2252
2253
2254 Here are the steps involved:
2255
2256
2257     # cd /usr/pkgsrc/chat/ircII
2258     # bmake install clean
2259     => ircii-20040820.tar.bz2 doesn't seem to exist on this system.
2260     => Attempting to fetch ircii-20040820.tar.bz2 from ftp://ircii.warped.com/pub/ircII/.
2261     => [559843 bytes]
2262     [FTP transfer snipped]
2263     150 Opening BINARY mode data connection for 'ircii-20040820.tar.bz2' (559843 bytes).
2264     100% |***************************************|   550 KB  110.34 KB/s   00:00 ETA
2265     226 Transfer complete.
2266     [FTP transfer snipped]
2267     221 Thank you for using the FTP service on bungi.sjc.warped.net.
2268     => Checksum SHA1 OK for ircii-20040820.tar.bz2.
2269     => Checksum RMD160 OK for ircii-20040820.tar.bz2.
2270     work -> /usr/obj/pkgsrc/chat/ircII/work
2271     ##=> Extracting for ircII-20040820
2272     #########################################################################=
2273     The supported build options for this package are:
2274
2275     socks4 socks5
2276
2277     You can select which build options to use by setting PKG_DEFAULT_OPTIONS
2278     or the following variable.  Its current value is shown:
2279
2280     
2281     PKG_OPTIONS.ircII (not defined)
2282
2283     #########################################################################=
2284     #########################################################################=
2285     The following variables will affect the build process of this package,
2286     ircII-20040820.  Their current value is shown below:
2287
2288     USE_INET6 = YES
2289
2290     You may want to abort the process now with CTRL-C and change their value
2291     before continuing.  Be sure to run `/usr/pkg/bin/bmake clean' after
2292     the changes.
2293     #########################################################################=
2294     ##=> Patching for ircII-20040820
2295     ##=> Applying pkgsrc patches for ircII-20040820
2296     ##=> Overriding tools for ircII-20040820
2297     ##=> Creating toolchain wrappers for ircII-20040820
2298     ##=> Configuring for ircII-20040820
2299     ...
2300     [configure output snipped]
2301     ...
2302     ##=>  Building for ircII-20040820
2303     ...
2304     [compilation output snipped]
2305     ...
2306     ##=>  Installing for ircII-20040820
2307     ...
2308     [installation output snipped]
2309     ...
2310     ##=> [Automatic manual page handling]
2311     ##=> Registering installation for ircII-20040820
2312     ##=> Cleaning for ircII-20040820
2313     #
2314
2315
2316
2317 <!-- XXX: mention /usr/pkg/etc/mk.conf for options, etc -->
2318
2319 As you can see, the only difference are the lines that tell you where the system is fetching the package's distfile from.
2320
2321
2322
2323 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. 
2324
2325
2326
2327 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.
2328
2329
2330
2331  **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.
2332
2333
2334
2335 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`.
2336
2337
2338
2339  **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:
2340
2341
2342
2343     
2344
2345     # bmake show-options
2346
2347
2348
2349
2350
2351  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:
2352
2353
2354
2355     
2356
2357     # bmake PKG_OPTIONS.ircII="-ssl"
2358
2359
2360
2361
2362
2363  An option is enabled if listed. It is disabled if it is prefixed by a minus sign.
2364
2365
2366
2367 #### Dealing with imake 
2368
2369
2370
2371 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.
2372
2373
2374
2375 ### Removing Installed Packages 
2376
2377
2378
2379 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:
2380
2381     
2382
2383     # cd /usr/pkgsrc/chat/ircII
2384     # make deinstall
2385     ##=>  Deinstalling for ircII-20040820
2386
2387
2388 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.
2389
2390
2391
2392 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].
2393
2394
2395
2396 ### Packages and Disk Space 
2397
2398
2399
2400 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.
2401
2402
2403
2404 ### Upgrading Packages
2405
2406
2407  **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.
2408
2409
2410
2411 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!
2412
2413
2414
2415 pkg_chk requires a few steps in order to work correctly. They are listed here.
2416
2417     # pkg_chk -g # make initial list of installed packages
2418     # pkg_chk -r  # remove all packages that are not up to date and packages that depend on them
2419     # pkg_chk -a  # install all missing packages (use binary packages, this is the default
2420     # pkg_chk -as # install all missing packages (build from source)
2421
2422 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.
2423
2424     # cd /usr/pkgsrc/pkgtools/pkg_rolling-replace/
2425     # bmake install
2426
2427 Once pkg_rolling-replace is installed you can update the packages through the following steps.
2428
2429     # cd /usr && make pkgsrc-update
2430     # pkg_rolling-replace -u
2431
2432 If some package like "bmake" does not get updated and throws an error during the above steps you can update it manually.
2433 Inside the packages directory (devel/bmake in this case)
2434
2435     # env USE_DESTDIR=full bmake package
2436     # bmake clean-depends clean
2437
2438 And Go to the packages directory and install the binary package with
2439
2440     # pkg_add -u <pkg_name> (i.e. the name of the .tgz file).
2441
2442 Also you can use "pkgin" to update software using binary packages just like apt or yum.
2443
2444     # cd /usr/pkgsrc/pkgtools/pkgin/
2445     # bmake install
2446
2447 Once "pkgin" is installed edit "/usr/pkg/etc/pkgin/repositories.conf" to contain the line ( for i386 packages ).
2448
2449     http://avalon.dragonflybsd.org/packages/i386/DragonFly-2.5/stable/All
2450
2451 Then you can run the following commands to get the packages updated.
2452
2453     # pkgin update
2454     # pkgin full-upgrade 
2455
2456     
2457     
2458     ## Post-installation Activities 
2459
2460
2461
2462 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.
2463
2464
2465
2466 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:
2467
2468
2469
2470
2471 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
2472
2473     # pkg_info -L foopackage-1.0.0 | less
2474
2475 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
2476
2477       
2478
2479     pkg_info | grep -i foopackage
2480
2481   
2482 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.
2483
2484
2485 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.
2486
2487
2488 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
2489
2490       
2491
2492     # pkg_info foopackage-1.0.0
2493
2494   
2495 A `WWW:` line, if present, should provide a URL for the application's web site.
2496
2497
2498 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.
2499
2500
2501
2502
2503
2504
2505 ## Dealing with Broken Packages 
2506
2507
2508
2509 If you come across a package that does not work for you, there are a few things you can do, including:
2510
2511
2512
2513   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!
2514
2515   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/) .
2516
2517   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.
2518
2519
2520
2521
2522
2523
2524
2525 CategoryHandbook
2526
2527 CategoryHandbook-pkgsrc
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547 # The X Window System 
2548
2549
2550
2551 ***Updated for X.Org's X11 server by Ken Tom and Marc Fonvieille. Updated for DragonFly by Victor Balada Diaz.***
2552
2553
2554 ## Synopsis 
2555
2556 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.
2557
2558
2559
2560 After reading this chapter, you will know:
2561
2562
2563
2564
2565 * The various components of the X Window System, and how they interoperate.
2566 * How to install and configure X11.
2567 * How to install and use different window managers.
2568 * How to use True***Type® fonts in X11.
2569 * How to set up your system for graphical logins ( **XDM** ).
2570
2571
2572
2573 Before reading this chapter, you should:
2574
2575 * Know how to install additional third-party software. Compare the pkgsrc chapter of the handbook.
2576
2577 **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.
2578
2579
2580
2581
2582
2583
2584 # Understanding X 
2585
2586 ## The Window Manager 
2587
2588
2589
2590 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.
2591
2592
2593
2594 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.
2595
2596
2597
2598 In addition, the  **KDE**  and  **GNOME**  desktop environments both have their own window managers which integrate with the desktop. Each window manager also has a different configuration mechanism; some expect configuration file written by hand, others feature GUI tools for most of the configuration tasks; at least one ( **Sawfish** ) has a configuration file written in a dialect of the Lisp language.
2599
2600
2601
2602
2603
2604 # Installing X1
2605
2606 **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.
2607
2608 To build and install  **X.org**  from the pkgsrc framework:
2609     # echo "X11_TYPE=modular" >> /etc/mk.conf
2610
2611
2612 Now 5 different packages need to be built and installed:
2613
2614     # cd /usr/pkgsrc/x11/modular-xorg-server
2615     # bmake install clean
2616     # cd /usr/pkgsrc/meta-pkgs/modular-xorg-drivers
2617     # bmake install clean
2618     # cd /usr/pkgsrc/meta-pkgs/modular-xorg-fonts
2619     # bmake install clean
2620     # cd /usr/pkgsrc/meta-pkgs/modular-xorg-libs
2621     # bmake install clean
2622     # cd /usr/pkgsrc/meta-pkgs/modular-xorg-apps
2623     # bmake install clean
2624
2625
2626
2627 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:
2628   
2629
2630     # pkg_radd modular-xorg-server
2631     # pkg_radd modular-xorg-drivers
2632     # pkg_radd modular-xorg-libs
2633     # pkg_radd modular-xorg-apps
2634     # pkg_radd modular-xorg-fonts
2635
2636
2637 **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.
2638
2639
2640
2641
2642 ----
2643
2644
2645
2646 ## 5.4 X11 Configuration 
2647
2648
2649
2650           ***Contributed by Christopher Shumway. ***
2651
2652
2653
2654 ### 5.4.1 Before Starting 
2655
2656
2657
2658 Before configuration of X11 the following information about the target system is needed:
2659
2660
2661
2662
2663 * Monitor specifications
2664
2665
2666 * Video Adapter chipset
2667
2668
2669 * Video Adapter memory
2670
2671
2672
2673 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.
2674
2675
2676
2677 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.
2678
2679
2680
2681 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.
2682
2683
2684
2685 ### 5.4.2 Configuring X11 
2686
2687
2688
2689 As of version 7.3, Xorg can often work without any configuration file by simply typing at prompt:
2690
2691     
2692
2693     % startx
2694
2695
2696
2697
2698 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:
2699
2700    
2701
2702     # Xorg -configure
2703
2704
2705 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.
2706
2707
2708
2709 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:
2710
2711    
2712
2713     # Xorg -config xorg.conf.new
2714
2715
2716 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.
2717
2718
2719
2720 **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`:
2721
2722         # rcenable moused
2723
2724
2725
2726 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:
2727
2728     
2729
2730     Section "Monitor"
2731             Identifier   "Monitor0"
2732             VendorName   "Monitor Vendor"
2733             ModelName    "Monitor Model"
2734             HorizSync    30-107
2735             VertRefresh  48-120
2736     EndSection
2737
2738
2739
2740 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.
2741
2742
2743
2744 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:
2745
2746             Option       "DPMS"
2747
2748
2749
2750 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:
2751
2752
2753
2754     
2755
2756     Section "Screen"
2757             Identifier "Screen0"
2758             Device     "Card0"
2759             Monitor    "Monitor0"
2760             DefaultDepth 24
2761             SubSection "Display"
2762                     Viewport  0 0
2763                     Depth     24
2764                     Modes     "1024x768"
2765             EndSubSection
2766     EndSection
2767
2768
2769 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.
2770
2771
2772 Finally, write the configuration file and test it using the test mode given above.
2773
2774
2775 **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.
2776
2777
2778
2779 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`.
2780
2781
2782
2783     # cp xorg.conf.new /etc/X11/xorg.conf
2784
2785
2786
2787 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).
2788
2789
2790 **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.
2791
2792
2793 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.
2794
2795
2796
2797 ### 5.4.3 Advanced Configuration Topics 
2798
2799
2800
2801 #### 5.4.3.1 Configuration with Intel® i810 Graphics Chipsets 
2802
2803
2804
2805 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.
2806
2807
2808 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`.
2809
2810
2811 **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:
2812
2813               Option "NoDDC"
2814
2815
2816
2817
2818
2819 ----
2820
2821
2822
2823
2824
2825
2826 # 5.5 Using Fonts in X11 
2827 <!-- XXX: do we really need this? -->
2828
2829
2830  ***Contributed by Murray Stokely. ***
2831
2832
2833
2834 ## 5.5.1 Type1 Fonts 
2835
2836
2837
2838  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).
2839
2840
2841
2842  To install the Freefonts font collection from the pkgsrc framework, run the following commands:
2843
2844
2845
2846      
2847
2848     # cd /usr/pkgsrc/fonts/freefonts
2849
2850     # bmake install clean
2851
2852
2853
2854
2855
2856  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:
2857
2858
2859
2860      
2861
2862     FontPath "/usr/pkg/lib/X11/fonts/freefont/"
2863
2864
2865
2866
2867
2868  Alternatively, at the command line in the X session run:
2869
2870
2871
2872      
2873
2874     % xset fp+ /usr/pkg/lib/X11/fonts/freefont/
2875
2876     % xset fp rehash
2877
2878
2879
2880
2881
2882  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).
2883
2884
2885
2886 ## 5.5.2 TrueType® Fonts 
2887
2888
2889
2890   **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.
2891
2892
2893
2894      
2895
2896     Load  "freetype"
2897
2898
2899
2900
2901
2902  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).
2903
2904
2905
2906      
2907
2908     # cd /usr/pkg/xorg/lib/X11/fonts/TrueType
2909
2910     # ttmkfdir -o fonts.dir
2911
2912
2913
2914
2915
2916  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
2917
2918
2919
2920     
2921
2922     % xset fp+ /usr/pkg/xorg/lib/X11/fonts/TrueType
2923
2924     % xset fp rehash
2925
2926
2927
2928
2929
2930  or add a `FontPath` line to the `xorg.conf` file.
2931
2932
2933
2934  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.
2935
2936
2937
2938 ## 5.5.3 Anti-Aliased Fonts 
2939
2940
2941
2942  ***Updated by Joe Marcus Clarke. ***
2943
2944
2945
2946  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.
2947
2948
2949
2950  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).
2951
2952
2953
2954  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:
2955
2956
2957
2958      
2959
2960           <?xml version="1.0"?>;
2961
2962           <!DOCTYPE fontconfig SYSTEM "fonts.dtd">
2963
2964           <fontconfig>
2965
2966
2967
2968
2969
2970  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`:
2971
2972
2973
2974      
2975
2976     <dir>/path/to/my/fonts</dir>;
2977
2978
2979
2980
2981
2982  After adding new fonts, and especially new font directories, you should run the following command to rebuild the font caches:
2983
2984
2985
2986      
2987
2988     # fc-cache -f
2989
2990
2991
2992
2993
2994  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:
2995
2996
2997
2998      
2999
3000             <match target="font">
3001
3002                 <test name#"size" compare"less">
3003
3004                     <double>14</double>
3005
3006                 </test>
3007
3008                 <edit name#"antialias" mode"assign">
3009
3010                     <bool>false</bool>
3011
3012                 </edit>
3013
3014             </match>
3015
3016             <match target="font">
3017
3018                 <test name#"pixelsize" compare"less" qual="any">
3019
3020                     <double>14</double>
3021
3022                 </test>
3023
3024                 <edit mode#"assign" name"antialias">
3025
3026                     <bool>false</bool>
3027
3028                 </edit>
3029
3030             </match>
3031
3032
3033
3034
3035
3036  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:
3037
3038
3039
3040      
3041
3042            <match target#"pattern" name"family">
3043
3044                <test qual#"any" name"family">
3045
3046                    <string>fixed</string>
3047
3048                </test>
3049
3050                <edit name#"family" mode"assign">
3051
3052                    <string>mono</string>
3053
3054                </edit>
3055
3056             </match>
3057
3058             <match target#"pattern" name"family">
3059
3060                 <test qual#"any" name"family">
3061
3062                     <string>console</string>
3063
3064                 </test>
3065
3066                 <edit name#"family" mode"assign">
3067
3068                     <string>mono</string>
3069
3070                 </edit>
3071
3072             </match>
3073
3074
3075
3076
3077
3078  (this aliases the other common names for fixed fonts as `"mono"`), and then add:
3079
3080
3081
3082      
3083
3084              <match target#"pattern" name"family">
3085
3086                  <test qual#"any" name"family">
3087
3088                      <string>mono</string>
3089
3090                  </test>
3091
3092                  <edit name#"spacing" mode"assign">
3093
3094                      <int>100</int>
3095
3096                  </edit>
3097
3098              </match>
3099
3100
3101
3102
3103
3104  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`:
3105
3106
3107
3108      
3109
3110              <match target#"pattern" name"family">
3111
3112                  <test qual#"any" name"family">
3113
3114                      <string>Helvetica</string>
3115
3116                  </test>
3117
3118                  <edit name#"family" mode"assign">
3119
3120                      <string>sans-serif</string>
3121
3122                  </edit>
3123
3124              </match>
3125
3126
3127
3128
3129
3130  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.
3131
3132
3133
3134  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.
3135
3136
3137
3138  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.
3139
3140
3141
3142  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:
3143
3144
3145
3146      
3147
3148              <match target="font">
3149
3150                  <test qual#"all" name"rgba">
3151
3152                      <const>unknown</const>
3153
3154                  </test>
3155
3156                  <edit name#"rgba" mode"assign">
3157
3158                      <const>rgb</const>
3159
3160                  </edit>
3161
3162              </match>
3163
3164
3165
3166
3167
3168    **Note:** Depending on the sort of display, `rgb` may need to be changed to `bgr`, `vrgb` or `vbgr`: experiment and see which works best.
3169
3170
3171
3172
3173
3174  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.
3175
3176
3177 ----
3178
3179
3180
3181 # 5.6 The X Display Manager 
3182
3183  ***Contributed by Seth Kingsley.***
3184
3185
3186
3187 ## 5.6.1 Overview 
3188
3189
3190
3191  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.
3192
3193
3194
3195  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.
3196
3197
3198
3199 ## 5.6.2 Using XDM 
3200
3201
3202
3203  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:
3204
3205
3206
3207      
3208
3209     ttyv8   "/usr/pkg/xorg/bin/xdm -nodaemon"  xterm   off secure
3210
3211
3212
3213
3214
3215  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.
3216
3217
3218
3219 ## 5.6.3 Configuring XDM 
3220
3221
3222
3223  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:
3224
3225
3226 [[!table  data="""
3227 <tablestyle="width:100%">  **File**  |  **Description**
3228 <tablestyle="width:100%"> `Xaccess` | Client authorization ruleset.
3229 `Xresources` | Default X resource values.
3230 `Xservers` | List of remote and local displays to manage.
3231 `Xsession` | Default session script for logins.
3232 `Xsetup_`* | Script to launch applications before the login interface.
3233 `xdm-config` | Global configuration for all displays running on this machine.
3234 `xdm-errors` | Errors generated by the server program.
3235 `xdm-pid` | The process ID of the currently running XDM. |
3236
3237 """]]
3238
3239
3240  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).
3241
3242
3243
3244  The default configuration is a simple rectangular login window with the hostname of the machine displayed at the top in a large font and "Login:" and "Password:" prompts below. This is a good starting point for changing the look and feel of  **XDM**  screens.
3245
3246
3247
3248 ### 5.6.3.1 Xaccess 
3249
3250
3251
3252  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.
3253
3254
3255
3256 ### 5.6.3.2 Xresources 
3257
3258
3259
3260  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.
3261
3262
3263
3264 ### 5.6.3.3 Xservers 
3265
3266
3267
3268  This is a list of the remote displays the chooser should provide as choices.
3269
3270
3271
3272 ### 5.6.3.4 Xsession 
3273
3274
3275
3276  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.
3277
3278
3279
3280 ### 5.6.3.5 Xsetup_* 
3281
3282
3283
3284  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`.
3285
3286
3287
3288 ### 5.6.3.6 xdm-config 
3289
3290
3291
3292  This contains settings in the form of app-defaults that are applicable to every display that this installation manages.
3293
3294
3295
3296 ### 5.6.3.7 xdm-errors 
3297
3298
3299
3300  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.
3301
3302
3303
3304 ## 5.6.4 Running a Network Display Server 
3305
3306
3307
3308  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:
3309
3310
3311
3312      
3313
3314     ! SECURITY: do not listen for XDMCP or Chooser requests
3315
3316     ! Comment out this line if you want to manage X terminals with xdm
3317
3318     DisplayManager.requestPort:     0
3319
3320
3321
3322
3323
3324  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.
3325
3326
3327
3328 ## 5.6.5 Replacements for XDM 
3329
3330
3331
3332  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.
3333
3334
3335 ----
3336
3337
3338
3339 # 5.7 Desktop Environments 
3340
3341  ***Contributed by Valentino Vaschetto. ***
3342
3343  This section describes the different desktop environments available for X on FreeBSD. A ***desktop environment*** can mean anything ranging from a simple window manager to a complete suite of desktop applications, such as  **KDE**  or  **GNOME** .
3344
3345
3346
3347 ## 5.7.1 GNOME 
3348
3349
3350
3351 ### 5.7.1.1 About GNOME 
3352
3353
3354
3355    **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.
3356
3357
3358
3359 ### 5.7.1.2 Installing GNOME 
3360
3361
3362
3363    **GNOME**  can be easily installed from a package or from the pkgsrc framework:
3364
3365
3366
3367   To install the  **GNOME**  package from the network, simply type:
3368
3369     # pkg_radd gnome
3370
3371
3372
3373
3374
3375   To build  **GNOME**  from source, use the ports tree:
3376
3377       
3378
3379     # cd /usr/pkgsrc/meta-pkgs/gnome
3380
3381     # bmake install clean
3382
3383
3384
3385   Once  **GNOME**  is installed, the X server must be told to start  **GNOME**  instead of a default window manager.
3386
3387
3388
3389   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.
3390
3391
3392
3393 **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:
3394
3395
3396
3397       
3398
3399     % echo "/usr/pkg/bin/gnome-session" > ~/.xinitrc
3400
3401
3402
3403
3404
3405   Next, type `startx`, and the  **GNOME**  desktop environment will be started.
3406
3407
3408 **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** :
3409
3410
3411
3412         
3413
3414     % echo "#!/bin/sh" > ~/.xsession
3415
3416     % echo "/usr/pkg/bin/gnome-session" >> ~/.xsession
3417
3418     % chmod +x ~/.xsession
3419
3420
3421
3422
3423
3424   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** .
3425
3426
3427
3428 ### 5.7.1.3 Anti-aliased Fonts with GNOME 
3429
3430
3431
3432   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).
3433   
3434   So, with up-to-date software, anti-aliasing is possible within the  **GNOME**  desktop. Just go to  **Applications->Desktop Preferences->Font** , and select either Best shapes, Best contrast, or Subpixel smoothing (LCDs). For a GTK+ application that is not part of the  **GNOME**  desktop, set the environment variable `GDK_USE_XFT` to `1` before launching the program.
3435
3436
3437
3438 ## 5.7.2 KDE 
3439
3440
3441
3442 ### 5.7.2.1 About KDE 
3443
3444
3445
3446   **KDE**  is an easy to use contemporary desktop environment. Some of the things that  **KDE**  brings to the user are:
3447
3448 * A beautiful contemporary desktop
3449
3450 * A desktop exhibiting complete network transparency
3451
3452 * An integrated help system allowing for convenient, consistent access to help on the use of the  **KDE**  desktop and its applications
3453
3454 * Consistent look and feel of all  **KDE**  applications
3455
3456 * Standardized menu and toolbars, keybindings, color-schemes, etc.
3457
3458 * Internationalization:  **KDE**  is available in more than 40 languages
3459
3460 * Centralized consisted dialog driven desktop configuration
3461
3462 * A great number of useful  **KDE**  applications
3463
3464   **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/).
3465
3466
3467
3468 ### 5.7.2.2 Installing KDE 
3469
3470
3471  Just as with  **GNOME**  or any other desktop environment, the easiest way to install  **KDE**  is through the pkgsrc framework or from a package:
3472
3473
3474
3475  To install the  **KDE**  package from the network, simply type:
3476
3477    # pkg_radd kde3
3478
3479  or if you prefer the newer **KDE 4**, type:
3480  
3481    # pkg_radd kde4
3482
3483  [pkg_radd(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#pkg_radd&section1) will automatically fetch the latest version of the application.
3484
3485
3486  To build  **KDE**  from source, use the pkgsrc framework:
3487
3488     # cd /usr/pkgsrc/meta-pkgs/kde3
3489
3490     # bmake install clean
3491
3492
3493
3494
3495
3496  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:
3497
3498
3499     % echo "exec startkde" > ~/.xinitrc
3500
3501
3502  Now, whenever the X Window System is invoked with `startx`,  **KDE**  will be the desktop.
3503
3504  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.
3505
3506
3507
3508 ## 5.7.3 More Details on KDE 
3509
3510
3511
3512  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.
3513
3514  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.
3515
3516
3517
3518 ### 5.7.3.1 The KDE Display Manager 
3519
3520
3521
3522  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.
3523
3524
3525
3526  To enable  **kdm** , the `ttyv8` entry in `/etc/ttys` has to be adapted. The line should look as follows:
3527   
3528
3529     ttyv8 "/usr/pkg/bin/kdm -nodaemon" xterm on secure
3530
3531
3532     
3533 ## 5.7.4 XFce 
3534
3535
3536
3537 ### 5.7.4.1 About XFce 
3538
3539
3540   **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:
3541
3542 * A simple, easy-to-handle desktop
3543
3544 * Fully configurable via mouse, with drag and drop, etc
3545
3546 * Main panel similar to  **CDE** , with menus, applets and applications launchers
3547
3548 * Integrated window manager, file manager, sound manager,  **GNOME**  compliance module, and other things
3549
3550 * Themeable (since it uses GTK+)
3551
3552 * Fast, light and efficient: ideal for older/slower machines or machines with memory limitations
3553
3554
3555 More information on  **XFce**  can be found on the [XFce website](http://www.xfce.org/).
3556
3557
3558
3559 ### 5.7.4.2 Installing XFce 
3560
3561
3562
3563  A binary package for  **XFce**  exists. To install, simply type:
3564
3565     # pkg_radd xfce4
3566
3567
3568  Alternatively, to build from source, use the pkgsrc framework:
3569
3570    
3571
3572     # cd /usr/pkgsrc/meta-pkgs/xfce4
3573
3574     # bmake install clean
3575
3576
3577
3578
3579  Now, tell the X server to launch  **XFce**  the next time X is started. Simply type this:
3580
3581     % echo "/usr/pkg/bin/startxfce4" > ~/.xinitrc
3582
3583
3584
3585  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).
3586
3587
3588
3589 <!-- XXX: FreeBSD's handbook has a nice user-oriented section about X applications here. maybe we should have one, too -->
3590
3591 ----
3592
3593
3594
3595
3596
3597
3598 <!-- XXX: break the stuff up here -->
3599
3600
3601 # II. System Administration 
3602
3603
3604
3605 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.
3606
3607
3608 ## Chapter 6 Configuration and Tuning 
3609
3610
3611 ***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.***
3612
3613
3614
3615 ## 6.1 Synopsis 
3616
3617
3618
3619 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.
3620
3621
3622 After reading this chapter, you will know:
3623
3624 * How to efficiently work with file systems and swap partitions.
3625
3626 * The basics of `rc.conf` configuration and `rc.d` startup systems.
3627
3628 * How to configure and test a network card.
3629
3630 * How to configure virtual hosts on your network devices.
3631
3632 * How to use the various configuration files in `/etc`.
3633
3634 * How to tune DragonFly using `sysctl` variables.
3635
3636 * How to tune disk performance and modify kernel limitations.
3637
3638
3639 Before reading this chapter, you should:
3640
3641 * Understand UNIX® and DragonFly basics ([Chapter 3](basics.html)).
3642
3643 * Be familiar with the basics of kernel configuration/compilation ([Chapter 9](kernelconfig.html)).
3644
3645
3646
3647
3648
3649
3650
3651 CategoryHandbook
3652
3653 Category
3654
3655
3656
3657
3658
3659
3660
3661 ## 6.2 Initial Configuration 
3662
3663
3664 ### 6.2.1 Partition Layout 
3665
3666
3667 #### 6.2.1.1 Base Partitions 
3668
3669 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`.
3670 <!-- 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? -->
3671
3672
3673
3674 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.
3675
3676
3677
3678 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.
3679
3680
3681
3682 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.
3683
3684
3685
3686 #### 6.2.1.2 Swap Partition 
3687
3688
3689
3690 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.
3691 <!-- XXX: do we really recommend double the RAM for swap? IMHO the amount of RAM should be more than enough -->
3692
3693
3694 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.
3695
3696
3697
3698 #### 6.2.1.3 Why Partition? 
3699
3700
3701
3702 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`.
3703
3704 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.
3705 <!-- XXX: again, same story about the edges of disks... -->
3706
3707
3708
3709 CategoryHandbook
3710
3711 CategoryHandbook-configuration
3712
3713
3714
3715
3716
3717 ## 6.3 Core Configuration 
3718
3719
3720
3721 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.
3722
3723
3724
3725 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.
3726
3727
3728
3729 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.
3730
3731
3732
3733 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:
3734
3735 * rc.conf:
3736
3737         hostname="node15.example.com"
3738
3739         network_interfaces="fxp0 lo0"
3740
3741         ifconfig_fxp0="inet 10.1.1.1"
3742
3743   
3744
3745
3746 * rc.conf.site: 
3747
3748         defaultrouter="10.1.1.254"
3749
3750         saver="daemon"
3751
3752         blanktime="100"
3753
3754   
3755
3756
3757
3758 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.
3759
3760
3761
3762 Upgrading the system using `make world` will not overwrite the `rc.conf` file, so system configuration information will not be lost.
3763
3764
3765 CategoryHandbook
3766
3767 CategoryHandbook-configuration
3768
3769
3770
3771
3772 ## Application Configuration 
3773
3774
3775
3776 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.
3777
3778
3779
3780 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.
3781
3782
3783
3784 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.
3785
3786
3787
3788 For example, consider the contents of the directory `/usr/pkg/etc/httpd`:
3789
3790
3791
3792     
3793
3794     total 90
3795
3796     -rw-r--r--  1 root  wheel  -   34K Jan 11 12:04 httpd.conf
3797
3798     -rw-r--r--  1 root  wheel  -   13K Jan 11 12:02 magic
3799
3800     -rw-r--r--  1 root  wheel  -   28K Jan 11 12:02 mime.types
3801
3802     -rw-r--r--  1 root  wheel  -   11K Jan 11 12:02 ssl.conf
3803
3804
3805
3806
3807     
3808     
3809     
3810     
3811     
3812
3813 ## Starting Services 
3814
3815
3816
3817 It is common for a system to host a number of services. These may be started in several different fashions, each having different advantages.
3818
3819
3820
3821 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.
3822
3823
3824 A generic startup script in `/usr/pkg/share/examples/rc.d` looks like:
3825
3826
3827
3828     
3829
3830     #!/bin/sh
3831
3832     echo -n ' FooBar'
3833
3834     
3835
3836     case "$1" in
3837
3838     start)
3839
3840             /usr/pkg/bin/foobar
3841
3842             ;;
3843
3844     stop)
3845
3846             kill -9 `cat /var/run/foobar.pid`
3847
3848             ;;
3849
3850     
3851 *)
3852
3853             echo "Usage: `basename $0` {start|stop}" >&2
3854
3855             exit 64
3856
3857             ;;
3858
3859     esac
3860
3861     
3862
3863     exit 0
3864
3865     
3866
3867
3868
3869
3870 <!-- XXX: I don't think we actually look in /usr/pkg/share/examples/rc.d -->
3871
3872 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:
3873
3874
3875
3876     
3877
3878     # chmod 755 "FooBar.sh"
3879
3880
3881
3882
3883
3884 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.
3885
3886
3887
3888 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.
3889
3890
3891
3892  **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.
3893
3894
3895
3896 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.
3897
3898
3899
3900 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.
3901
3902
3903
3904
3905
3906
3907
3908 CategoryHandbook
3909
3910 CategoryHandbook-configuration
3911
3912
3913
3914
3915
3916
3917
3918 ## Configuring the cron Utility 
3919
3920 <!-- XXX: can't really comment on this. someone please revise it -->
3921
3922
3923 ***Contributed by Tom Rhodes. ***
3924
3925
3926
3927 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.
3928
3929
3930
3931 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.
3932
3933
3934
3935  **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.
3936
3937
3938
3939 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`.
3940
3941
3942
3943 Let us take a look at the `/etc/crontab` file (the system crontab):
3944
3945
3946
3947     
3948
3949     # /etc/crontab - root's crontab for DragonFly
3950
3951     #
3952
3953     #                                                                  (1)
3954
3955     #
3956
3957     SHELL=/bin/sh
3958
3959     PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin                            (2)
3960
3961     HOME=/var/log
3962
3963     #
3964
3965     #
3966
3967     #minute     hour    mday    month   wday    who     command            (3)
3968
3969     #
3970
3971     #
3972
3973     
3974     */5 *       *       *       *       root    /usr/libexec/atrun (4)
3975
3976
3977
3978
3979
3980  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.
3981
3982
3983
3984  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.
3985
3986
3987
3988  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.
3989
3990
3991
3992  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.
3993
3994
3995
3996 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.
3997
3998
3999
4000 ### Installing a Crontab 
4001
4002
4003
4004  **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.
4005
4006
4007
4008 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:
4009
4010
4011
4012     
4013
4014     % crontab crontab-file
4015
4016
4017
4018
4019
4020 In this example, `crontab-file` is the filename of a `crontab` that was previously created.
4021
4022
4023
4024 There is also an option to list installed `crontab` files: just pass the `-l` option to `crontab` and look over the output.
4025
4026
4027
4028 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.
4029
4030
4031
4032 If you later want to remove your user `crontab` completely, use `crontab` with the `-r` option.
4033
4034
4035
4036
4037
4038
4039
4040 CategoryHandbook
4041
4042 CategoryHandbook-configuration
4043
4044
4045
4046
4047
4048 ## 6.7 Using rc under DragonFly 
4049
4050
4051
4052 ***Contributed by Tom Rhodes. ***
4053
4054
4055
4056 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:
4057
4058
4059
4060     
4061
4062     # /etc/rc.d/sshd restart
4063
4064
4065
4066
4067
4068 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`:
4069
4070
4071     natd_enable="YES"
4072
4073
4074
4075 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.
4076
4077
4078 Another way to add services to the automatic startup/shutdown is to type, for example for `natd`,
4079
4080      # rcenable natd
4081
4082
4083 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:
4084
4085
4086
4087     
4088
4089     # /etc/rc.d/sshd forcerestart
4090
4091
4092
4093
4094
4095 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:
4096
4097
4098
4099     
4100
4101     # /etc/rc.d/sshd rcvar
4102
4103     # sshd
4104
4105     $sshd_enable=YES
4106
4107
4108
4109
4110
4111  **Note:** The second line (`# sshd`) is the output from the `rc.d` script, not a `root` prompt.
4112
4113
4114
4115 To determine if a service is running, a `status` option is available. For instance to verify that `sshd` is actually started:
4116
4117
4118
4119     
4120
4121     # /etc/rc.d/sshd status
4122
4123     sshd is running as pid 433.
4124
4125
4126
4127
4128
4129 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.
4130
4131
4132
4133 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.
4134
4135
4136
4137 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:
4138
4139
4140
4141
4142 * `PROVIDE`: Specifies the services this file provides.
4143
4144
4145 * `REQUIRE`: Lists services which are required for this service. This file will run ***after*** the specified services.
4146
4147
4148 * `BEFORE`: Lists services which depend on this service. This file will run ***before*** the specified services.
4149
4150
4151 * 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.
4152
4153   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.
4154
4155
4156
4157 By using this method, an administrator can easily control system services without the hassle of ***runlevels*** like some other UNIX® operating systems.
4158
4159
4160
4161 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.
4162
4163 ### Using DragonFly's rcrun(8) 
4164
4165 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)
4166
4167 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.
4168
4169
4170
4171 The remaining commands are:
4172
4173
4174
4175 [[!table  data="""
4176   **disable**  | Sets the corresponding `_enable` variable in rc.conf(5) to ***NO*** and runs the stop command. 
4177   **enable**   | Sets the corresponding `_enable` variable in rc.conf(5) to ***YES*** and runs the start command. 
4178   **list**  | Shows the status of the specified scripts.  If no argument is specified, the status of all scripts is shown. |
4179
4180 """]]
4181
4182
4183 To enable the [dntpd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=dntpd&section=8) service, you can use:
4184
4185      # rcenable dntpd
4186      
4187  
4188
4189 To check if [dntpd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=dntpd&section=8) is running you can use the following command:
4190
4191     
4192
4193     # rclist dntpd
4194
4195     rcng_dntpd=stopped
4196
4197
4198
4199 To start [dntpd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=dntpd&section=8):
4200
4201
4202
4203     
4204
4205     # rcstart dntpd
4206
4207     Running /etc/rc.d/dntpd start
4208
4209     Starting dntpd.
4210
4211
4212
4213 Restart and stop works the same way:
4214
4215     
4216
4217     # rcrestart dntpd
4218
4219     Stopping dntpd.
4220
4221     Starting dntpd.
4222
4223     
4224
4225     # rcstop dntpd
4226
4227     Stopping dntpd.
4228
4229
4230
4231
4232
4233 If a service is not enabled in `/etc/rc.conf`, but you want it start anyway, execute the following:
4234
4235     
4236
4237     # rcforce dntpd
4238
4239     Running /etc/rc.d/dntpd forcestart
4240
4241     Starting dntpd.
4242
4243
4244
4245 #### Notes 
4246
4247
4248
4249 [[!table  data="""
4250 <tablestyle="width:100%"> [(1)](configtuning-rcng.html#AEN4751) | Previously this was used to define *BSD dependent features.
4251 | |
4252
4253 """]]
4254
4255
4256
4257
4258
4259
4260
4261 ## 6.8 Setting Up Network Interface Cards 
4262
4263
4264
4265 ***Contributed by Marc Fonvieille. ***
4266
4267
4268
4269 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.
4270
4271
4272
4273 ### 6.8.1 Locating the Correct Driver 
4274
4275
4276
4277 Before you begin, you should know the model of the card you have, the chip it u